# Requirements Document

## Introduction

This specification defines the requirements for adding semi-major axis based normalization as an alternative normalization method for 3D Elliptic Fourier Analysis (EFA) in the ktch library.

Currently, the 2D EFA normalization (`_normalize_2d`) uses the semi-major axis length of the first harmonic ellipse as the scale factor, while the 3D EFA normalization (`_normalize_3d`) uses `sqrt(π·a·b)` (derived from the first harmonic ellipse area). This asymmetry means:

- **2D**: `scale = sqrt(a_s² + c_s²)` = semi-major axis length
- **3D**: `scale = sqrt(π·a₁·b₁)` = square root of ellipse area

This feature introduces a semi-major axis based normalization option for 3D EFA that aligns the scaling convention with the 2D case. The semi-major axis normalization uses the semi-major axis length `a₁` as the scale factor and aligns the semi-major axis direction as the primary orientation reference, providing a direct 3D extension of the Kuhl-Giardina (1982) normalization.

Both normalization methods (area-based and semi-major-axis-based) are valid approaches with different trade-offs: area-based normalization is more robust when the ellipse eccentricity varies, while semi-major-axis normalization provides a more direct correspondence with the 2D convention and is the natural choice when the first harmonic is well-conditioned.

## Requirements

### Requirement 1: Semi-Major Axis Normalization Method for 3D

**Objective:** As a morphometrics researcher, I want to normalize 3D EFA coefficients using the semi-major axis of the first harmonic ellipse as the scale factor, so that I can apply a normalization convention consistent with 2D EFA.

#### Acceptance Criteria

1. When `transform` is called with `n_dim=3`, `norm=True`, and the normalization method is set to semi-major axis, the EllipticFourierAnalysis shall use the semi-major axis length `a₁` of the first harmonic ellipse as the scale factor for normalization.
2. The EllipticFourierAnalysis shall apply the same reorientation (ZXZ Euler angles), phase shift (k·φ₁), and direction correction (sign of y-sine component) steps as the existing area-based normalization, differing only in the scale factor.
3. The EllipticFourierAnalysis shall produce first-harmonic coefficients that are canonical when using semi-major axis normalization (i.e., the normalized first harmonic has a fixed, predictable structure where the semi-major axis length equals 1).

### Requirement 2: Normalization Method Selection

**Objective:** As a morphometrics researcher, I want to choose between area-based and semi-major-axis-based normalization methods, so that I can select the approach most appropriate for my data and analysis goals.

#### Acceptance Criteria

1. The EllipticFourierAnalysis shall accept a parameter to select the normalization method for 3D data.
2. When the normalization method is not explicitly specified for 3D data, the EllipticFourierAnalysis shall default to the existing area-based normalization (`sqrt(π·a₁·b₁)`), preserving backward compatibility.
3. When the normalization method is set to semi-major axis, the EllipticFourierAnalysis shall use the semi-major axis length `a₁` as the scale factor.
4. The EllipticFourierAnalysis shall validate the normalization method parameter and raise an informative error for unsupported values.

### Requirement 3: Orientation and Scale Return for Semi-Major Axis Normalization

**Objective:** As a morphometrics researcher, I want to retrieve the scale factor from semi-major axis normalization, so that I can analyze size variation using the semi-major axis length.

#### Acceptance Criteria

1. When `return_orientation_scale=True` and the normalization method is set to semi-major axis, the EllipticFourierAnalysis shall return the semi-major axis length `a₁` as the scale value.
2. The EllipticFourierAnalysis shall return the same orientation parameters (ZXZ Euler angles and phase angle) regardless of the normalization method selected, since orientation determination is independent of the scale factor.

### Requirement 4: Inverse Transform Compatibility

**Objective:** As a morphometrics researcher, I want `inverse_transform` to correctly reconstruct outlines from semi-major-axis-normalized coefficients, so that I can visualize shapes from normalized data.

#### Acceptance Criteria

1. When `inverse_transform` is called with `norm=True` on semi-major-axis-normalized coefficients, the EllipticFourierAnalysis shall reconstruct coordinate values with the centroid zeroed (DC components set to zero), consistent with the existing behavior.
2. The EllipticFourierAnalysis shall produce reconstructed 3D outlines that are consistent with the normalization: applying `transform(norm=True)` followed by `inverse_transform(norm=True)` shall yield a normalized shape that is translation-free, scale-normalized, and orientation-aligned, regardless of the normalization method.

### Requirement 5: Backward Compatibility

**Objective:** As a library user, I want existing 2D and 3D EFA workflows to remain unchanged when I upgrade, so that my analysis pipelines are not broken.

#### Acceptance Criteria

1. The EllipticFourierAnalysis shall preserve identical behavior for `n_dim=2` with any `norm` setting (no change to `_normalize_2d` or `_transform_single_2d`).
2. When the normalization method parameter is not specified, the EllipticFourierAnalysis shall produce identical output to the current implementation for all `n_dim=3` operations.
3. The EllipticFourierAnalysis shall not remove or rename any existing public API methods or parameters.

### Requirement 6: Testing and Validation

**Objective:** As a developer, I want comprehensive tests for semi-major axis normalization, so that correctness is verified against known mathematical properties and regression is prevented.

#### Acceptance Criteria

1. The EllipticFourierAnalysis shall include unit tests verifying that semi-major axis normalization produces invariant coefficients under translation (shifting coordinates).
2. The EllipticFourierAnalysis shall include unit tests verifying that semi-major axis normalization produces invariant coefficients under uniform scaling (multiplying coordinates by a constant).
3. The EllipticFourierAnalysis shall include unit tests verifying that semi-major axis normalization produces invariant coefficients under rotation (applying an arbitrary 3D rotation matrix to coordinates).
4. The EllipticFourierAnalysis shall include unit tests verifying that semi-major axis normalization produces invariant coefficients under starting-point shift (cyclic permutation of outline points).
5. The EllipticFourierAnalysis shall include a test verifying that the semi-major axis length of the normalized first harmonic equals 1 (up to numerical tolerance).
6. The EllipticFourierAnalysis shall include a test verifying that area-based normalization continues to produce the same results as before (regression test).
