rowingdata 3.7.3__tar.gz → 3.8.0__tar.gz

{rowingdata-3.7.3/rowingdata.egg-info → rowingdata-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: rowingdata
-Version: 3.7.3
+Version: 3.8.0
 Summary: The rowingdata library to create colorful plots from CrewNerd, Painsled and other rowing data tools
 Home-page: https://github.com/sanderroosendaal/rowingdata
 Author: Sander Roosendaal
@@ -546,8 +546,10 @@ The available data fields are
 * ' StrokeDistance (meters)'
 * ' DriveTime (ms)'
 * ' StrokeRecoveryTime (ms)'
-* ' AverageDriveForce (lbs)'
-* ' PeakDriveForce (lbs)'
+* ' AverageDriveForce (N)' (preferred; SI units)
+* ' PeakDriveForce (N)' (preferred; SI units)
+* ' AverageDriveForce (lbs)' (legacy; still supported)
+* ' PeakDriveForce (lbs)' (legacy; still supported)
 * 'cum_dist'
 
 Oarlock parsers (NK Logbook) may add: ``catch``, ``finish``,
@@ -556,17 +558,22 @@ Oarlock parsers (NK Logbook) may add: ``catch``, ``finish``,
 If imported from TCX, Rowpro, or other tools, some data fields may not contain
 useful information. 
 
-=================
-CSV File Standard
-=================
+=======================
+rowingdata CSV Columns
+=======================
 
-The basic rowingdata class reads CSV files that adher to the standard
-described here. Any parser implementation should adher to the minimum
-standard as described here.
+This section describes the dataframe schema used by the ``rowingdata`` class.
+It is this package's own column layout, not a vendor-neutral standard. For a
+cross-vendor interchange format, see the Rowing Data Standard at
+https://github.com/MoveLab-Studio/rowing-data-standard, which rowingdata
+targets when exporting FIT.
 
-Please send to me any CSV file that adhers to the standard described here
+Any parser implementation feeding the ``rowingdata`` class should produce at
+least the columns described below.
+
+Please send to me any CSV file that follows the layout described here
 but does not parse well in the "rowingdata" module. I will update the module
-and add the file to standard testing. 
+and add the file to regression testing. 
 
 Field Names (Columns)
 ----------------------
@@ -583,14 +590,23 @@ The standard field names are:
 * ' StrokeDistance (meters)'
 * ' DriveTime (ms)'
 * ' StrokeRecoveryTime (ms)'
-* ' AverageDriveForce (lbs)'
-* ' PeakDriveForce (lbs)'
+* ' AverageDriveForce (N)' (preferred; SI units)
+* ' PeakDriveForce (N)' (preferred; SI units)
+* ' AverageDriveForce (lbs)' (legacy; still supported)
+* ' PeakDriveForce (lbs)' (legacy; still supported)
 * ' lapIdx'
 * ' ElapsedTime (sec)'
 
 Optional (Oarlock/NK Logbook): ``catch``/``catchAngle``, ``finish``/``finishAngle``,
 ``slip``, ``wash``, ``peakforceangle``, ``effectiveLength``.
 
+Planned for dual oarlock (port/starboard symmetry): ``catch_port``, ``catch_starboard``,
+``finish_port``, ``finish_starboard``, ``slip_port``, ``slip_starboard``, ``wash_port``,
+``wash_starboard``, ``peakforceangle_port``, ``peakforceangle_starboard``,
+``effectiveLength_port``, ``effectiveLength_starboard``. See *Dual oarlock
+(port/starboard)* below. **Note:** rowingdata does not yet implement parsing or
+export for these per-side columns.
+
 The CSV file adheres to the US conventions, with fields
 separated by a comma (',')
 and using the dot '.' as the decimal symbol. 
@@ -792,14 +808,12 @@ The duration of the recovery part. See Drive Time for the definition. Drive Time
 Average Drive Force
 --------------------
 
-Field name: ' AverageDriveForce (lbs)' / ' AverageDriveForce (N)'
+Field name: ' AverageDriveForce (N)' (preferred) or ' AverageDriveForce (lbs)' (legacy)
 
-Unit: lbs - or N, see below
+Unit: newtons (N), or pounds (lb) for older files and tools
 
-Currently implemented is only the field name and value in lbs. In the future,
-we will implement ' AverageDriveForce (N)' so we can report in SI units.
-
-This should be the part of the handle force that does actual work.
+Use **Newtons** for new data and integrations. **Pounds** remain supported for
+backward compatibility. This should be the part of the handle force that does actual work.
 
 For dynamic ergs and OTW rowing this is not sufficient to describe the
 complete stroke dynamics, so additional fields can be defined, for example
@@ -822,9 +836,9 @@ as opposed to an average over time or oar angles.
 Peak Drive Force
 ------------------
 
-Field name: ' PeakDriveForce (lbs)' or ' PeakDriveForce (N)'
+Field name: ' PeakDriveForce (N)' (preferred) or ' PeakDriveForce (lbs)' (legacy)
 
-Unit: lbs (currently) or N (supported in the future)
+Unit: newtons (N), or pounds (lb) for older files and tools
 
 See discussion about measuring forces under Average Drive Force.
 
@@ -840,11 +854,14 @@ source: NK Logbook uses these columns).
 These fields come from NK Logbook (Oarlock) and similar OTW
 measurement systems. They describe rigging geometry and blade angles:
 
-* **catch**, **finish** – oar angles at catch and finish (degrees).
-  NK uses catchAngle, finishAngle.
+* **catch**, **finish** – oar angles at catch and finish (degrees),
+  using the rowing convention where **0° = oar perpendicular to the boat's
+  longitudinal axis**. Negative values indicate the catch direction (oar blade
+  toward bow, handle toward stern); positive values indicate the finish direction
+  (oar blade toward stern, handle toward bow). NK uses catchAngle, finishAngle.
 * **slip** – blade slip angle.
 * **wash** – wash/backwash angle.
-* **peakforceangle** – oar angle at peak force.
+* **peakforceangle** – oar angle at peak force (same 0° = perpendicular convention).
 * **effectiveLength** – effective lever length (rigging geometry). *Not*
   the same as Drive Length: Effective Length is the horizontal component
   from pin to handle (a rigging/setup measure, often in cm), whereas
@@ -852,6 +869,16 @@ measurement systems. They describe rigging geometry and blade angles:
   stroke (typically 1.2–1.5 m). Both may appear in the same dataset;
   they serve different purposes.
 
+Dual oarlock (port/starboard)
+..............................
+
+When a rower uses two smart oarlocks, oarlock metrics can be reported per side:
+port (left) and starboard (right). Each metric may appear as a per-side column
+(e.g. ``catch_port``, ``catch_starboard``); the unsuffixed summary column
+(``catch``) is the average of the two sides when both exist, and the value of
+whichever side is present otherwise. **Note:** rowingdata does not yet
+implement parsing or FIT export for these per-side columns.
+
 Lap Identifier
 -------------------
 
@@ -940,6 +967,26 @@ Boat bearing.
 Release Notes:
 ================
 
+Unreleased
+----------
+
+- **Breaking change to exported FIT file contents.** FIT export now follows the
+  Rowing Data Standard (https://github.com/MoveLab-Studio/rowing-data-standard,
+  Draft v0.1). The ``exporttofit`` API is unchanged, but the bytes it writes are
+  not: the developer application ID is now the standard UUID, ``DriveLength``
+  and ``EffectiveLength`` are encoded in millimetres rather than metres,
+  ``AverageBoatSpeed`` uses scale 255, stroke rate moves to field ID 93, and
+  stroke work to field ID 19. Consumers that hardcoded the previous rowingdata
+  application ID or the old metre-based scales must be updated. ``FITParser``
+  still reads files written by rowingdata 3.7.3 and earlier.
+- In-stroke curve fields are emitted under a separate, private application ID,
+  because those field IDs are not allocated in the standard's registry and so
+  carry no interoperable meaning.
+- Removed ``docs/FIT_STANDARD.md`` and ``docs/FIT_STANDARD.pdf``. The standard is
+  maintained by a committee at
+  https://github.com/MoveLab-Studio/rowing-data-standard, which is the single
+  source of truth; this repository no longer ships a copy.
+
 0.97.x
 ------
 

{rowingdata-3.7.3 → rowingdata-3.8.0}/README.rst

@@ -514,8 +514,10 @@ The available data fields are
 * ' StrokeDistance (meters)'
 * ' DriveTime (ms)'
 * ' StrokeRecoveryTime (ms)'
-* ' AverageDriveForce (lbs)'
-* ' PeakDriveForce (lbs)'
+* ' AverageDriveForce (N)' (preferred; SI units)
+* ' PeakDriveForce (N)' (preferred; SI units)
+* ' AverageDriveForce (lbs)' (legacy; still supported)
+* ' PeakDriveForce (lbs)' (legacy; still supported)
 * 'cum_dist'
 
 Oarlock parsers (NK Logbook) may add: ``catch``, ``finish``,
@@ -524,17 +526,22 @@ Oarlock parsers (NK Logbook) may add: ``catch``, ``finish``,
 If imported from TCX, Rowpro, or other tools, some data fields may not contain
 useful information. 
 
-=================
-CSV File Standard
-=================
+=======================
+rowingdata CSV Columns
+=======================
 
-The basic rowingdata class reads CSV files that adher to the standard
-described here. Any parser implementation should adher to the minimum
-standard as described here.
+This section describes the dataframe schema used by the ``rowingdata`` class.
+It is this package's own column layout, not a vendor-neutral standard. For a
+cross-vendor interchange format, see the Rowing Data Standard at
+https://github.com/MoveLab-Studio/rowing-data-standard, which rowingdata
+targets when exporting FIT.
 
-Please send to me any CSV file that adhers to the standard described here
+Any parser implementation feeding the ``rowingdata`` class should produce at
+least the columns described below.
+
+Please send to me any CSV file that follows the layout described here
 but does not parse well in the "rowingdata" module. I will update the module
-and add the file to standard testing. 
+and add the file to regression testing. 
 
 Field Names (Columns)
 ----------------------
@@ -551,14 +558,23 @@ The standard field names are:
 * ' StrokeDistance (meters)'
 * ' DriveTime (ms)'
 * ' StrokeRecoveryTime (ms)'
-* ' AverageDriveForce (lbs)'
-* ' PeakDriveForce (lbs)'
+* ' AverageDriveForce (N)' (preferred; SI units)
+* ' PeakDriveForce (N)' (preferred; SI units)
+* ' AverageDriveForce (lbs)' (legacy; still supported)
+* ' PeakDriveForce (lbs)' (legacy; still supported)
 * ' lapIdx'
 * ' ElapsedTime (sec)'
 
 Optional (Oarlock/NK Logbook): ``catch``/``catchAngle``, ``finish``/``finishAngle``,
 ``slip``, ``wash``, ``peakforceangle``, ``effectiveLength``.
 
+Planned for dual oarlock (port/starboard symmetry): ``catch_port``, ``catch_starboard``,
+``finish_port``, ``finish_starboard``, ``slip_port``, ``slip_starboard``, ``wash_port``,
+``wash_starboard``, ``peakforceangle_port``, ``peakforceangle_starboard``,
+``effectiveLength_port``, ``effectiveLength_starboard``. See *Dual oarlock
+(port/starboard)* below. **Note:** rowingdata does not yet implement parsing or
+export for these per-side columns.
+
 The CSV file adheres to the US conventions, with fields
 separated by a comma (',')
 and using the dot '.' as the decimal symbol. 
@@ -760,14 +776,12 @@ The duration of the recovery part. See Drive Time for the definition. Drive Time
 Average Drive Force
 --------------------
 
-Field name: ' AverageDriveForce (lbs)' / ' AverageDriveForce (N)'
+Field name: ' AverageDriveForce (N)' (preferred) or ' AverageDriveForce (lbs)' (legacy)
 
-Unit: lbs - or N, see below
+Unit: newtons (N), or pounds (lb) for older files and tools
 
-Currently implemented is only the field name and value in lbs. In the future,
-we will implement ' AverageDriveForce (N)' so we can report in SI units.
-
-This should be the part of the handle force that does actual work.
+Use **Newtons** for new data and integrations. **Pounds** remain supported for
+backward compatibility. This should be the part of the handle force that does actual work.
 
 For dynamic ergs and OTW rowing this is not sufficient to describe the
 complete stroke dynamics, so additional fields can be defined, for example
@@ -790,9 +804,9 @@ as opposed to an average over time or oar angles.
 Peak Drive Force
 ------------------
 
-Field name: ' PeakDriveForce (lbs)' or ' PeakDriveForce (N)'
+Field name: ' PeakDriveForce (N)' (preferred) or ' PeakDriveForce (lbs)' (legacy)
 
-Unit: lbs (currently) or N (supported in the future)
+Unit: newtons (N), or pounds (lb) for older files and tools
 
 See discussion about measuring forces under Average Drive Force.
 
@@ -808,11 +822,14 @@ source: NK Logbook uses these columns).
 These fields come from NK Logbook (Oarlock) and similar OTW
 measurement systems. They describe rigging geometry and blade angles:
 
-* **catch**, **finish** – oar angles at catch and finish (degrees).
-  NK uses catchAngle, finishAngle.
+* **catch**, **finish** – oar angles at catch and finish (degrees),
+  using the rowing convention where **0° = oar perpendicular to the boat's
+  longitudinal axis**. Negative values indicate the catch direction (oar blade
+  toward bow, handle toward stern); positive values indicate the finish direction
+  (oar blade toward stern, handle toward bow). NK uses catchAngle, finishAngle.
 * **slip** – blade slip angle.
 * **wash** – wash/backwash angle.
-* **peakforceangle** – oar angle at peak force.
+* **peakforceangle** – oar angle at peak force (same 0° = perpendicular convention).
 * **effectiveLength** – effective lever length (rigging geometry). *Not*
   the same as Drive Length: Effective Length is the horizontal component
   from pin to handle (a rigging/setup measure, often in cm), whereas
@@ -820,6 +837,16 @@ measurement systems. They describe rigging geometry and blade angles:
   stroke (typically 1.2–1.5 m). Both may appear in the same dataset;
   they serve different purposes.
 
+Dual oarlock (port/starboard)
+..............................
+
+When a rower uses two smart oarlocks, oarlock metrics can be reported per side:
+port (left) and starboard (right). Each metric may appear as a per-side column
+(e.g. ``catch_port``, ``catch_starboard``); the unsuffixed summary column
+(``catch``) is the average of the two sides when both exist, and the value of
+whichever side is present otherwise. **Note:** rowingdata does not yet
+implement parsing or FIT export for these per-side columns.
+
 Lap Identifier
 -------------------
 
@@ -908,6 +935,26 @@ Boat bearing.
 Release Notes:
 ================
 
+Unreleased
+----------
+
+- **Breaking change to exported FIT file contents.** FIT export now follows the
+  Rowing Data Standard (https://github.com/MoveLab-Studio/rowing-data-standard,
+  Draft v0.1). The ``exporttofit`` API is unchanged, but the bytes it writes are
+  not: the developer application ID is now the standard UUID, ``DriveLength``
+  and ``EffectiveLength`` are encoded in millimetres rather than metres,
+  ``AverageBoatSpeed`` uses scale 255, stroke rate moves to field ID 93, and
+  stroke work to field ID 19. Consumers that hardcoded the previous rowingdata
+  application ID or the old metre-based scales must be updated. ``FITParser``
+  still reads files written by rowingdata 3.7.3 and earlier.
+- In-stroke curve fields are emitted under a separate, private application ID,
+  because those field IDs are not allocated in the standard's registry and so
+  carry no interoperable meaning.
+- Removed ``docs/FIT_STANDARD.md`` and ``docs/FIT_STANDARD.pdf``. The standard is
+  maintained by a committee at
+  https://github.com/MoveLab-Studio/rowing-data-standard, which is the single
+  source of truth; this repository no longer ships a copy.
+
 0.97.x
 ------
 

rowingdata-3.8.0/rowingdata/data/fit_export_spec.json

@@ -0,0 +1,88 @@
+{
+  "version": 2,
+  "_comment": "Authoritative FIT developer field definitions for rowingdata fitwrite. Field IDs, scales and units must match the Rowing Data Standard registry at https://github.com/MoveLab-Studio/rowing-data-standard (registry/field-ids.md); that repository is the source of truth, this file is only rowingdata's machine-readable copy of the subset it emits. v2: mm precision for DriveLength/PeakForcePositionAbs (scale 1000); StrokeRate dev field (93); instroke curve Y-scale registry.",
+  "instroke_dynamic": {
+    "summary_start": 20,
+    "summary_id_padding": "ceil_to_10",
+    "curve_start": 60
+  },
+  "instroke_curve_types": {
+    "HandleForceCurve": {
+      "y_scale": 10,
+      "y_units": "N",
+      "default_abscissa": "HANDLE_DISTANCE_UNIFORM_M"
+    },
+    "BoatAcceleratorCurve": {
+      "y_scale": 100,
+      "y_units": "m/s^2",
+      "default_abscissa": "TIME_UNIFORM_MS"
+    },
+    "OarAngleVelocityCurve": {
+      "y_scale": 10,
+      "y_units": "deg/s",
+      "default_abscissa": "TIME_UNIFORM_MS"
+    },
+    "SeatCurve": {
+      "y_scale": 255,
+      "y_units": "m",
+      "default_abscissa": "HANDLE_DISTANCE_UNIFORM_M"
+    }
+  },
+  "abscissa_enum": {
+    "UNKNOWN": 0,
+    "TIME_UNIFORM_MS": 1,
+    "HANDLE_DISTANCE_UNIFORM_M": 2,
+    "OAR_ANGLE_UNIFORM_DEG": 3,
+    "NORMALIZED_DRIVE_0_1": 4
+  },
+  "instroke_axis_field_ids": [90, 91, 92],
+  "always_emit_field_ids": [9, 90, 91, 92],
+  "instroke_column_map": {
+    "curve_data": "HandleForceCurve",
+    "boat accelerator curve": "BoatAcceleratorCurve",
+    "oar angle velocity curve": "OarAngleVelocityCurve",
+    "seat curve": "SeatCurve"
+  },
+  "developer_fields": [
+    {"field_id": 0, "group": "rowing", "fit_name": "DriveLength", "base_type": "UINT16", "size": 2, "scale": 1, "units": "mm", "df_columns": [" DriveLength (meters)"]},
+    {"field_id": 1, "group": "rowing", "fit_name": "StrokeDriveTime", "base_type": "UINT16", "size": 2, "scale": 1, "units": "ms", "df_columns": [" DriveTime (ms)"]},
+    {"field_id": 2, "group": "rowing", "fit_name": "DragFactor", "base_type": "UINT16", "size": 2, "scale": 1, "units": "", "df_columns": [" DragFactor"]},
+    {"field_id": 3, "group": "rowing", "fit_name": "StrokeRecoveryTime", "base_type": "UINT16", "size": 2, "scale": 1, "units": "ms", "df_columns": [" StrokeRecoveryTime (ms)"]},
+    {"field_id": 4, "group": "rowing", "fit_name": "AverageDriveForceLbs", "base_type": "UINT16", "size": 2, "scale": 10, "units": "lbs", "df_columns": [" AverageDriveForce (lbs)"]},
+    {"field_id": 5, "group": "rowing", "fit_name": "PeakDriveForceLbs", "base_type": "UINT16", "size": 2, "scale": 10, "units": "lbs", "df_columns": [" PeakDriveForce (lbs)"]},
+    {"field_id": 6, "group": "rowing", "fit_name": "AverageDriveForceN", "base_type": "UINT16", "size": 2, "scale": 10, "units": "N", "df_columns": [" AverageDriveForce (N)"]},
+    {"field_id": 7, "group": "rowing", "fit_name": "PeakDriveForceN", "base_type": "UINT16", "size": 2, "scale": 10, "units": "N", "df_columns": [" PeakDriveForce (N)"]},
+    {"field_id": 8, "group": "rowing", "fit_name": "AverageBoatSpeed", "base_type": "UINT16", "size": 2, "scale": 255, "units": "m/s", "df_columns": [" AverageBoatSpeed (m/s)"]},
+    {"field_id": 9, "group": "rowing", "fit_name": "WorkoutState", "base_type": "UINT8", "size": 1, "scale": 1, "units": "", "df_columns": [" WorkoutState"]},
+    {"field_id": 10, "group": "metadata", "fit_name": "RecordingStrategy", "base_type": "UINT8", "size": 1, "scale": 1, "units": "", "df_columns": [], "message_type": "session"},
+    {"field_id": 19, "group": "rowing", "fit_name": "StrokeWork", "base_type": "UINT16", "size": 2, "scale": 1, "units": "J", "df_columns": [" WorkPerStroke (joules)", "driveenergy"]},
+    {"field_id": 93, "group": "rowing", "fit_name": "StrokeRate", "base_type": "UINT16", "size": 2, "scale": 100, "units": "spm", "df_columns": [" Cadence (stokes/min)"]},
+
+    {"field_id": 11, "group": "oarlock", "fit_name": "Catch", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["catch", " catch", "catchAngle"]},
+    {"field_id": 12, "group": "oarlock", "fit_name": "Finish", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["finish", " finish", "finishAngle"]},
+    {"field_id": 13, "group": "oarlock", "fit_name": "Slip", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["slip", " slip"]},
+    {"field_id": 14, "group": "oarlock", "fit_name": "Wash", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["wash", " wash"]},
+    {"field_id": 15, "group": "oarlock", "fit_name": "PeakForceAngle", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["peakforceangle", " peakforceangle"]},
+    {"field_id": 16, "group": "oarlock", "fit_name": "EffectiveLength", "base_type": "UINT16", "size": 2, "scale": 1, "units": "mm", "df_columns": ["effectiveLength", " effectiveLength", "effective length"]},
+
+    {"field_id": 200, "group": "oarlock_dual", "dual_pair": "catch", "side": "port", "fit_name": "CatchPort", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["catch_port", "catchAngle_port"]},
+    {"field_id": 201, "group": "oarlock_dual", "dual_pair": "catch", "side": "starboard", "fit_name": "CatchStarboard", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["catch_starboard", "catchAngle_starboard"]},
+    {"field_id": 202, "group": "oarlock_dual", "dual_pair": "finish", "side": "port", "fit_name": "FinishPort", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["finish_port", "finishAngle_port"]},
+    {"field_id": 203, "group": "oarlock_dual", "dual_pair": "finish", "side": "starboard", "fit_name": "FinishStarboard", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["finish_starboard", "finishAngle_starboard"]},
+    {"field_id": 204, "group": "oarlock_dual", "dual_pair": "slip", "side": "port", "fit_name": "SlipPort", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["slip_port"]},
+    {"field_id": 205, "group": "oarlock_dual", "dual_pair": "slip", "side": "starboard", "fit_name": "SlipStarboard", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["slip_starboard"]},
+    {"field_id": 206, "group": "oarlock_dual", "dual_pair": "wash", "side": "port", "fit_name": "WashPort", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["wash_port"]},
+    {"field_id": 207, "group": "oarlock_dual", "dual_pair": "wash", "side": "starboard", "fit_name": "WashStarboard", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["wash_starboard"]},
+    {"field_id": 208, "group": "oarlock_dual", "dual_pair": "peakforceangle", "side": "port", "fit_name": "PeakForceAnglePort", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["peakforceangle_port"]},
+    {"field_id": 209, "group": "oarlock_dual", "dual_pair": "peakforceangle", "side": "starboard", "fit_name": "PeakForceAngleStarboard", "base_type": "SINT16", "size": 2, "scale": 10, "units": "deg", "df_columns": ["peakforceangle_starboard"]},
+    {"field_id": 210, "group": "oarlock_dual", "dual_pair": "effectiveLength", "side": "port", "fit_name": "EffectiveLengthPort", "base_type": "UINT16", "size": 2, "scale": 1, "units": "mm", "df_columns": ["effectiveLength_port"]},
+    {"field_id": 211, "group": "oarlock_dual", "dual_pair": "effectiveLength", "side": "starboard", "fit_name": "EffectiveLengthStarboard", "base_type": "UINT16", "size": 2, "scale": 1, "units": "mm", "df_columns": ["effectiveLength_starboard"]},
+
+    {"field_id": 17, "group": "peak_position", "fit_name": "PeakForcePositionNorm", "base_type": "UINT16", "size": 2, "scale": 1, "units": "", "df_columns": ["rel_peak_force_pos", "PeakForcePositionNorm", "% of Stroke Complete When Peak Force Is Reached"], "transformer": "peak_norm", "clip_uint16_max": 10000},
+    {"field_id": 18, "group": "peak_position", "fit_name": "PeakForcePositionAbs", "base_type": "UINT16", "size": 2, "scale": 1, "units": "mm", "df_columns": ["peak_force_pos", "PeakForcePositionAbs"], "transformer": "peak_abs"},
+
+    {"field_id": 90, "group": "instroke_axis", "fit_name": "InstrokeAbscissaType", "base_type": "UINT8", "size": 1, "scale": 1, "units": "", "df_columns": []},
+    {"field_id": 91, "group": "instroke_axis", "fit_name": "InstrokeSampleInterval", "base_type": "UINT16", "size": 2, "scale": 1, "units": "", "df_columns": []},
+    {"field_id": 92, "group": "instroke_axis", "fit_name": "InstrokePointCount", "base_type": "UINT8", "size": 1, "scale": 1, "units": "", "df_columns": []}
+  ]
+}

rowingdata-3.8.0/rowingdata/fit_garmin_bridge.py

@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+"""
+Bridge Garmin / OpenRowingMonitor FIT messages (Split, SplitSummary, Workout, WorkoutStep)
+from fitparse into fit_tool GenericMessage for re-emission with rowingdata exports.
+
+Global message numbers 312 and 313 are not in fitparse's profile (shown as unknown_312 / unknown_313);
+they correspond to Split and SplitSummary in current Garmin FIT profiles.
+"""
+from __future__ import absolute_import
+
+from fit_tool.base_type import BaseType
+from fit_tool.definition_message import DefinitionMessage
+from fit_tool.endian import Endian
+from fit_tool.field import Field
+from fit_tool.field_definition import FieldDefinition
+from fit_tool.generic_message import GenericMessage
+
+from fitparse.base import FitFile as FitparseFitFile
+# Garmin FIT profile (extended): Split / SplitSummary message numbers
+MESG_SPLIT = 312
+MESG_SPLIT_SUMMARY = 313
+MESG_WORKOUT = 26
+MESG_WORKOUT_STEP = 27
+
+_DEFAULT_PRESERVE = (MESG_WORKOUT, MESG_WORKOUT_STEP, MESG_SPLIT_SUMMARY, MESG_SPLIT)
+
+
+def _fitparse_base_type_to_fit_tool(fp_bt):
+    """Map fitparse records.BaseType name to fit_tool BaseType."""
+    name = fp_bt.name.lower()
+    mapping = {
+        'enum': BaseType.ENUM,
+        'sint8': BaseType.SINT8,
+        'uint8': BaseType.UINT8,
+        'string': BaseType.STRING,
+        'sint16': BaseType.SINT16,
+        'uint16': BaseType.UINT16,
+        'sint32': BaseType.SINT32,
+        'uint32': BaseType.UINT32,
+        'float32': BaseType.FLOAT32,
+        'float64': BaseType.FLOAT64,
+        'byte': BaseType.BYTE,
+        'uint8z': BaseType.UINT8Z,
+        'uint16z': BaseType.UINT16Z,
+        'uint32z': BaseType.UINT32Z,
+        'uint64': BaseType.UINT64,
+        'sint64': BaseType.SINT64,
+    }
+    return mapping.get(name, BaseType.UINT8)
+
+
+def _field_definition_from_fitparse(fd):
+    bt = _fitparse_base_type_to_fit_tool(fd.base_type)
+    return FieldDefinition(field_id=fd.def_num, size=fd.size, base_type=bt)
+
+
+def _set_field_from_raw(fit_field, raw_value):
+    """Copy raw decoded value from fitparse into fit_tool Field.encoded_values."""
+    bt = fit_field.base_type
+    if raw_value is None:
+        inv = bt.invalid_raw_value() if hasattr(bt, 'invalid_raw_value') else 0
+        fit_field.set_encoded_value(0, inv, check_validity=False)
+        return
+    if isinstance(raw_value, tuple):
+        for i, rv in enumerate(raw_value):
+            fit_field.set_encoded_value(i, int(rv) & 0xFFFFFFFF, check_validity=False)
+        return
+    if bt == BaseType.STRING:
+        fit_field.growable = True
+        s = raw_value if isinstance(raw_value, str) else str(raw_value)
+        fit_field.set_value(0, s[: fit_field.size] if fit_field.size else s)
+        return
+    n = len(fit_field.encoded_values)
+    if n == 1:
+        fit_field.set_encoded_value(0, int(raw_value), check_validity=False)
+    else:
+        fit_field.set_encoded_value(0, int(raw_value), check_validity=False)
+
+
+def _generic_from_fitparse_data(def_mesg, data_msg, local_id):
+    """Build fit_tool DefinitionMessage + GenericMessage from fitparse messages."""
+    endian = Endian.LITTLE if def_mesg.endian == '<' else Endian.BIG
+    field_defs = [_field_definition_from_fitparse(fd) for fd in def_mesg.field_defs]
+    definition = DefinitionMessage(
+        local_id=local_id,
+        global_id=def_mesg.mesg_num,
+        endian=endian,
+        field_definitions=field_defs,
+        developer_field_definitions=[],
+    )
+    gen = GenericMessage(definition_message=definition, developer_fields=None)
+    # Zip field data: fitparse DataMessage.fields order matches def field_defs + dev
+    fp_fields = list(data_msg.fields)
+    for i, fd in enumerate(def_mesg.field_defs):
+        if i >= len(fp_fields):
+            break
+        fld = gen.get_field(fd.def_num)
+        if fld is None and i < len(gen.fields):
+            fld = gen.fields[i]
+        if fld is None:
+            continue
+        fv = fp_fields[i]
+        raw = fv.raw_value if fv.raw_value is not None else fv.value
+        _set_field_from_raw(fld, raw)
+    return definition, gen
+
+
+def iter_preserved_generic_messages(fit_path, mesg_nums=None):
+    """
+    Parse FIT with fitparse low-level API; yield (definition, GenericMessage) pairs
+    for each data message whose global mesg_num is in mesg_nums, in file order.
+    Local message IDs are reassigned uniquely for fit_tool (starting at 8 to avoid
+    clashing with common record/lap local IDs).
+    """
+    if mesg_nums is None:
+        mesg_nums = _DEFAULT_PRESERVE
+    mesg_set = set(mesg_nums)
+    f = FitparseFitFile(fit_path)
+    while f._parse_message():
+        pass
+    # Map (mesg_num, tuple of field def signatures) -> next local_id
+    # Use local_id >= 8 to avoid clashing with fit_tool defaults (record/lap/event often use 0–3).
+    def_key_to_local = {}
+    next_local = 8
+    for m in f._messages:
+        if getattr(m, 'type', None) != 'data':
+            continue
+        if m.mesg_num not in mesg_set:
+            continue
+        def_mesg = m.def_mesg
+        key = (m.mesg_num, tuple((fd.def_num, fd.size, fd.base_type.name) for fd in def_mesg.field_defs))
+        if key not in def_key_to_local:
+            def_key_to_local[key] = next_local
+            next_local += 1
+        local_id = def_key_to_local[key]
+        definition, gen = _generic_from_fitparse_data(def_mesg, m, local_id)
+        yield definition, gen
+
+
+def add_preserved_messages_to_builder(builder, fit_path, mesg_nums=None):
+    """
+    Add preserved native messages to a FitFileBuilder.
+
+    Emits each DefinitionMessage once (required by FIT), then each data message with
+    ``definition_message`` cleared so FitFileBuilder binds the message to the stored
+    definition (see fit_tool FitFileBuilder.add).
+    """
+    seen_def = set()
+    for definition, gen in iter_preserved_generic_messages(fit_path, mesg_nums=mesg_nums):
+        key = (definition.global_id, definition.local_id, tuple((fd.field_id, fd.size, fd.base_type) for fd in definition.field_definitions))
+        if key not in seen_def:
+            builder.add(definition)
+            seen_def.add(key)
+        gen.definition_message = None
+        builder.add(gen)