# CoMPAS Navlib Changelog

## v1.2.3 (2025-12-02)

### Feat

- add reset function to UUV_EKF
- Add warning handling for time jump scenarios in AHRS Hua filter
- Improve Hua AHRS filter stability with correct time-jump handling and magnetic-field fix
- Enhance input handling for attitude estimation functions with flexible array support
- **lcmlog**: add channel filtering support to read_log function
- **lcmlog**: add a field with the lcmtype name for each message

### Fix

- Update navlib/__init__.py
- LCM log merging to use raw binary approach
- **resample**: improve handling of new time vector and clarify extrapolation behavior
- **mbs_read_fnv**: update suffix handling for processed and raw files

## v1.2.2 (2025-11-21)

### Feat

- **lcmlog**: add channel filtering support to read_log function
- **lcmlog**: add a field with the lcmtype name for each message

### Fix

- **resample**: improve handling of new time vector and clarify extrapolation behavior
- **mbs_read_fnv**: update suffix handling for processed and raw files

## v1.2.1 (2025-08-06)

### Feat

- **quaternion**: add dedicated quaternion module

### Fix

- **uuv_ekf**: add covariance symmetrization after updates
- **uuv_ekf**: change attitud correction logic
- **uuv_ekf**: add warnings for negative and large time steps in prediction
- **uuv_ekf**: improve quaternion noise handling in UUV_EKF class

## v1.2.0 (2025-07-29)

### Feat

- **cal_dvl**: add latitude parameter to cal_dvl_acc_so3 for local gravity calculation
- **geo**: add local_gravity function to calculate local gravity based on latitude and depth
- **lcmlog**: add struct_to_dict function to convert nav_structtype to dictionary
- **attitude_estimation**: enhance complementary filters
- **logging**: improved logging level parsing
- **logging**: add logging module with documentation and updated function docstring
- **uuv_ekf**: add support for custom measurement covariance in correction methods
- **uuv_ekf**: correction_position extension
- **uuv_ekf**: split correction_ahrs

### Fix

- **attitude_estimation**: update magnetic field correction method for consistency and clarity
- **so3**: normalize quaternion outputs in hpr2quat, rph2quat, and rot2quat functions
- **cal_dvl**: change default method from 'ls' to 'min' in cal_dvl_acc_so3 function
- **filter**: improve outlier handling and threshold logic
- **filter_savgol**: improve outlier handling and threshold logic
- **filter_median**: minor fixes to median filter
- **attitude_estimation**: update ahrs_madgwick_filter return type to include additional data
- **madgwick_filter**: update test to include angular rate output
- **ahrs_madgwick_filter**: computation errors
- **ahrs_mahony_filter**: general improvements
- **.gitignore**: add missing Python bytecode and cache files to ignore list

### Refactor

- **attitude_estimation**: Hua filter refactoring
- **uuv_ekf**: extract quaternion normalization to _check_state_attitude method
- **uuv_ekf**: mahalanobis distance-based scaling
- **test_kalman_filter**: remove tests for unused _safe_nanmean method
- **uuv_ekf**: remove unused _safe_nanmean method

## v1.1.1 (2025-05-14)

### Feat

- **ekf**: add process noise covariance for velocity in UUV_EKF class as parameter

### Fix

- **ekf**: ensure timestamp is a numpy array in current_state concatenation
- **ekf**: ensure input quaternion is unit and has a positive scalar part

### Refactor

- **workflow**: remove push trigger from Python package test workflow
- **navdvl_kf**: update function signatures and return types to include full state vector
- **navdvl_dead_reckoning**: update return type to include full state vector and adjust tests accordingly
- **ekf**: include timestamp in state initialization and prediction methods
- **ekf**: update state vector to include timestamp and adjust state dimension
- **ekf**: rename parameter omega_body to angular_velocity for clarity
- **ekf**: remove setters for current_state and current_covariance for cleaner interface
- **ekf**: remove timestamp parameter from correction methods for cleaner interface

## v1.1.0 (2025-05-03)

### Feat

- **parsers**: add parser for MB-System fnv data files
- **nav**: add UUV_EKF for uncrewed underwater vehicle state estimation based on DVL, IMU/AHRS, depth sensor and USBL aiding using an extended Kalman filter, featured with Mahalanoobis distance-based outlier rejection, automatic fine tuning of process noise covariance and quaternion integration via exponential map.
- **workflow**: enhance Python package publish workflow to include documentation build and deploy to GitHub Pages
- **math**: add left and right quaternion product matrix functions

### Fix

- **ci**: upgrade pip, setuptools, and wheel before installing Poetry
- **vmath**: enhance remove_offset function to accept arrays and improve type checks
- **vmath**: update resample function to truncate new time vector outside old range and add warning
- **vmath**: improve handling of 1D and 2D matrices for derivative
- **vmath**: update remove_offset function to accept int or float as offset
- **workflow**: remove Python 3.8 test job from workflow
- **nav**: adjust return value of navdvl_dead_reckoning to exclude first rph element in state estimation
- **nav**: update navdvl_dead_reckoning to return orientation along with position

### Refactor

## v1.0.0 (2025-04-21)

### Feat

- **docs**: add repository name and URL to mkdocs configuration
- **docs**: update README with Python version badge and remove deprecated version from pyproject.toml
- **docs**: update README and mkdocs configuration with library features and installation instructions
- **docs**: add Time module documentation and update navigation
- **docs**: update Kalman Filter documentation and add State Estimation module documentation
- **docs**: add Kalman Filter module documentation and update navigation
- **docs**: add Attitude Estimation module documentation and update navigation
- **docs**: add LCM Logs module documentation and update navigation
- **docs**: add Geography module documentation and update navigation
- **docs**: add Seawater module documentation and update navigation
- **docs**: update AHRS Calibration module documentation and add Magnetometer Calibration module
- **docs**: add AHRS Calibration module documentation and update navigation
- **docs**: update heading levels and filter options in Math module documentation
- **docs**: add DVL Calibration module documentation and update navigation
- **docs**: enable source code display in Math module documentation
- **docs**: add Filters Math module documentation and update mkdocs navigation
- **docs**: add SE(3) Math module documentation and update mkdocs navigation
- **docs**: add SO(3) Math module documentation and update mkdocs navigation
- **docs**: add documentation for Array Math module and update vmath.py docstring
- **docs**: add initial documentation structure and license information
- **docs**: add mkdocs and mkdocstrings dependencies for documentation
- **ci**: update python-package-test.yml
- **ci**: add GitHub Actions workflow for Python package testing
- **time**: add timestamps_make_uniform function for generating uniformly spaced timestamps
- **time**: extend utime2datestr and datestr2utime to support lists and numpy arrays
- **time**: enhance utime2datestr to support lists and numpy arrays of timestamps
- **time**: add time_interval_indices function for filtering timestamps within a range
- **cal**: add cal_dvl_jck_so3 function and update imports
- **cal**: add new MAGYC calibration functions and update module exports
- **cal**: add SAR magnetometer calibration methods
- **cal**: refactor twostep functions for data centering and Fisher matrix calculations
- **cal**: add cal_mag_sphere_fit function and corresponding unit tests
- **cal**: add cal_mag_twostep_hi and cal_mag_twostep_hsi functions and corresponding tests
- **cal**: update cal_mag_ellipsoid_fit function and add unit tests for ellipsoid fitting
- **cal**: add cal_mag_magfactor3 function and update imports
- **test**: add unit tests for magnetometer calibration functions
- **cal**: add ellipsoit fit calibration for magnetometers
- **calib**: add cal_dvl_correct_by_sound_velocity function
- **calib**: add cal_dvl_acc_so3 function and update imports in navlib
- **calib**: ensure roll, pitch, and heading arrays are consistently shaped in cal_ahrs_so3 function
- **calib**: unwrap roll, pitch, and heading angles in cal_ahrs_so3 function to avoid discontinuities
- **calib**: add cal_ahrs_so3 function for AHRS extrinics calibration in SO(3)
- **so3**: add so3_optimization function for optimizing on SO(3) manifold
- **seawater**: add ctd2oxygen_saturation function with comprehensive input validation tests
- **seawater**: add ctp2pden function with comprehensive input validation tests
- **seawater**: implement ctd2salinity function with input validation
- **seawater**: implement ctp2salinity function with input validation
- **seawater**: add depth2pressure
- **seawater**: add ctd2svel
- **nav**: add madgwick filter
- **geo**: add method to convert from dms to decimal coordinates
- **vmath**: transpose function for 2D and 3D arrays
- **filters**: add modules with filters for ndim arrays
- **geo**: add multidimensional arrays capabilities
- **vmath**: add squeeze to (n, 1) or (1, n) arrays
- **state_estimation**: add state estimation module functions
- **kalman**: add kalman filter module

### Fix

- **docs**: update docs/index.md
- **docs**: python version in README.md
- update mkdocs.yml to use emoji extensions
- **cal_mag**: restore gtsam symbol shorthand import for compatibility
- **deps**: adjust gtsam dependency for Python compatibility
- **geo**: remove TODO comment for adding tests in dms_to_decimal function
- **cal**: rename objective function for SO3 calibration to improve clarity
- **cal**: low-pass filter cal_dvl_acc_so3
- **tests**: correct error messages for depth validation checks
- **geo**: dms_to_decimal parameters check
- **nav**: required parameters hua and mahonny filters
- **nav**: corrections to complementary filter

### Refactor

- restructure import logic
- **vmath**: move functions from so3 module to vmath module

## v0.1.7 (2024-11-23)

### Fix

- **time**:
  - Bugfix for time related to local time zones, now forced to UTC.

- **nav**:
  - Correct row of zeros for last state in kalman filter.

### Feat

- **geo**:
  - Add multidimensional arrays capabilities

- **filters**:
  - Add filter_median for a median filter with outliers removing capabilities.
  - Add filter_savgol for a Savitsky-Golay filter with outliers removing capabilities.
  - Add filter_lowpass for a Low Pass filter.
  - Add unit test for the module.

- **vmath**:
  - Add transpose function for 2D and 3D arrays

### Build

- Improve compatibility in dependencies for python ^3.8

## v0.1.6 (2024-09-16)

### Fix

- **vmath**:
  - Fix bugs on data checks.

## v0.1.6-a1 (2024-09-16)

### Fix

- **attitude_estimation**:
  - Multiple bugs in ahrs_mahony_filter, ahrs_hua_mahony_filter and ahrs_complementary_filter functions.
  - Adjust gains for ahrs_mahony_filter and ahrs_hua_mahony_filter functions based on the original papers.

### Feat

- **vmath**:
  - Add squeeze to remove extra dimensions from (n, 1) and (1, n) arrays.

### Docs

- **LICENSE**:
  - Update the license to MIT.

### Build

- Update dependencies versions.

## v0.1.6-a0 (2024-09-16)

### Feat

- **attitude_estimation**:
  - Add new functions to estimate attitude (ahrs_raw_rp, ahrs_raw_hdg, ahrs_raw_rph).
  - Add new functions to integrate the orientation frame using exponential coordinates (so3_integrator and so3_integrator_fast).
  - Add new functions with complimentary filters to estimate the attitude: ahrs_complementary_filter, ahrs_mahony_filter and ahrs_hua_mahony_filter.
  - Add unit tests for the new functions.

### Refactor

- **vmath**: Rename camelcase functions to snakecase and add flexibility for multidimensional arrays adding the `keepdims` parameter.
- **so3**: Rename camelcase functions to snakecase.
- **se3**: Rename camelcase functions to snakecase.

### Fix

- **time**: Fix the unit tests `test_utime2datestr` and `test_datestr2utime`, as the test case was set to local time instead of UTC time.

## v0.1.5 (2024-03-28)

### Fix

- Version update to 0.1.5 to match pypi version.

## v0.1.1 (2024-03-27)

### Fix

- Correct small changes regarding versions.

## v0.1.0 (2024-03-27)

### Feat

- **geography**: add geography module with test
  - This module provides functions for working with geographic coordinates.
  - The initial set of functions are:
    - latlon_to_zone_number: Determines the UTM zone number for a given latitude and longitude.
    - latlon_to_zone_letter: Determines the UTM zone letter for a given latitude.
    - ll2utm: Converts latitude and longitude to UTM coordinates.
    - utm2ll: Converts UTM coordinates to latitude and longitude.
    - deg2m_lat: Converts latitude from degrees to meters.
    - deg2m_lon: Converts longitude from degrees to meters.
    - ll2xy: Converts latitude and longitude to xy mercator coordinates from an origin.
    - xy2ll: Converts xy mercator coordinates to latitude and longitude from an origin.
  - A test file is provided to validate the functions.

- **time**: add time module with test
  - This module provides functions for working with time.
  - The initial set of functions are:
    - time_now: Returns the current time in microseconds since the epoch in local time.
    - time_now_utc: Returns the current time in microseconds since the epoch in UTC.
    - utime2datestr: Converts a Unix timestamp to a date string.
    - datestr2utime: Converts a date string to a Unix timestamp.

- **se3**: add SE3 module with test
  - This module provides functions to work with the Special Euclidean Group SE(3).
  - The initial set of functions are:
    - xyzrph2matrix: Takes the pose as xyzrph and computes the corresponding transformation matrix.
    - matrix2xyzrph: Computes the pose xyzrph from a transformation matrix.
    - matrix_inverse: Compute the inverse of a transformation matrix.
    - pose_diff: Compute the relative transformation between two poses.
    - adjoint: Computes the adjoint representation of a transformation matrix.
    - vec_to_se3: Converts a spacial velocity vector (spatial twist) into a (4, 4) matrix in se(3).
    - se3_to_vec: Convert a se(3) (4, 4) matrix into a spatial velocity vector (spatial twist) in R6.
    - axis_ang6: Convert the exponential coordinates of a homogeneous transformation S*theta to a screw axis-angle form.
    - matrix_exp6: Computes the matrix exponential of an se(3) representation of exponential coordinates of a homogeneous transformation.
    - matrix_log6: Compute the logarithm of a homogeneous transformation matrix in SE(3).
    - project_to_SE3: Projects a matrix to the closest matrix in SE(3) using singular value decomposition.
    - distance_to_SE3: Compute the frobenius norm to describe the distance of a matrix from the SE(3) manifold.
  - A test file is provided to validate the functions.

- **so3**: add SO3 module with test
  - This module provides functions to work in the special orthogonal group SO(3) and its Lie algebra so(3).
  - The initial set of functions are:
    - rot_inv(rot): Compute the inverse of a rotation matrix.
    - hpr2quat(hpr): Convert Heading, Pitch and Roll (HPR) angles to quaternion using the ZYX Euler angles convention.
    - rph2quat(rph): Convert Roll, Pitch, Heading (RPH) angles to quaternion using the ZYX Euler angles convention.
    - quat2hpr(quat): Convert quaternion to Heading, Pitch and Roll (HPR) angles using the ZYX Euler angles convention.
    - quat2rph(quat): Convert quaternion to Roll, Pitch, Heading (RPH) angles using the ZYX Euler angles convention.
    - hpr2rot(hpr): Convert Heading, Pitch and Roll (HPR) angles to SO(3) rotation matrix using the ZYX Euler angles convention.
    - rph2rot(rph): Convert Roll, Pitch, Heading (RPH) angles to SO(3) rotation matrix using the ZYX Euler angles convention.
    - quat2rot(quat): Convert quaternion to a rotation matrix in SO(3) using the ZYX Euler angles convention.
    - rot2hpr(rot): Convert SO(3) rotation matrix to Roll, Pitch, Heading (RPH) angles using the ZYX Euler angles convention.
    - rot2rph(rot): Convert SO(3) rotation matrix to Roll, Pitch, Heading (RPH) angles using the ZYX Euler angles convention.
    - rot2quat(rot): Convert SO(3) rotation matrix to quaternion using the ZYX Euler angles convention.
    - rot_diff(rot_1, rot_2): Compute the relative rotation between two matrices.
    - vec_to_so3(vec): Compute the skew-symmetric representation for a vector of R3.
    - so3_to_vec(mat): Convert a so3 matrix into a R3 vector.
    - axis_ang3(vec): Converts a R3 representing a rotation into a exponential coordinates parametrization.
    - matrix_exp3(mat): Compute the matrix exponential of a matrix in so(3) representing the exponential coordinates for rotation.
    - matrix_log3(mat): Compute the matrix logarithm of a matrix in SO(3) representing the exponential coordinates for rotation.
    - project_to_so3(mat): Project a matrix in R3 to SO(3).
    - distance_so3(mat_1, mat_2): Compute the distance between two matrices in SO(3).
  - A test file is provided to validate the functions.

- **lcmlog**: add lcmlog module with parsing tools
  - This module contains functions to parse LCMLogs to a nav_structtype object or to save them as pickle files.
  - The initial set of functions are:
    - dict_to_struct: Convert a dictionary to a nav_structtype object.
    - read_log: Read a LCMLog file and return a nav_structtype object.
    - msg_getfields: Extracts the slots containing the field names from an lcm_msg object.
    - msg_getconstants: Extracts the constant attributes from an lcm_msg object.
    - msg_to_dict: Converts an LCM message to a dictionary. This function is recursive and can handle nested messages.
    - delete_status_msg: Deletes a status message from the stderr.
    - parse_and_save: Parse and LCM log file and save it to a pickle file based on a dictionary.
  - A test file is provided to validate the functions.

- **vmath**: add vmath module
  - This module provides a set of functions to perform operations in arrays as vectors or matrices and as lists.
  - The initial set of functions are:
    - norm: Returns the norm of a vector or matrix.
    - normalize: Returns the normalized vector or matrix.
    - mean: Returns the mean of a vector or matrix.
    - median: Returns the median of a vector or matrix.
    - std: Returns the standard deviation of a vector or matrix.
    - min: Returns the minimum value of a vector or matrix.
    - max: Returns the maximum value of a vector or matrix.
    - print_stats: Prints the statistics of a vector or matrix.
    - remove_offset: Removes a constant offset from a vector or matrix.
    - remove_mean: Removes the mean from a vector or matrix.
    - remove_median: Removes the median from a vector or matrix.
    - difference: Returns the difference of a vector or matrix.
    - derivative: Returns the derivative of a vector or matrix.
    - resample: Resamples a signal to a new time vector.
    - distance_traveled: Returns the distance traveled by a vector or matrix.
    - saturate: Saturates a vector or matrix.
    - wrap360: Wraps an input of angles between 0 and 360 degrees.
    - wrap180: Wraps an input of angles between -180 and 180 degrees.
    - wrap2pi: Wraps an input of angles between 0 and 2pi radians.
    - wrap1pi: Wraps an input of angles between -pi and pi radians.
    - unwrap2pi: Unwraps an input of angles wrapped between 0 and 2pi radians.
    - unwrap1pi: Unwraps an input of angles wrapped between -pi and pi radians.
    - unwrap360: Unwraps an input of angles wrapped between 0 and 360 degrees.
    - unwrap180: Unwraps an input of angles wrapped between -180 and 180 degrees.
    - wrapunwrap: Wraps and unwraps an input of angles between 0 and 2pi radians.
    - wrapunwrap360: Wraps and unwraps an input of angles between 0 and 360 degrees.
  - A test file is provided to validate the functions.

### Fix

- **lcmlog**: fix issues related to lcmlog parser and converter
