DOCSEARCHbyAlgolia
Submit Docs

fitdecode

repository·master·Indexed 42 days ago

https://github.com/polyvertex/fitdecode

A high-performance, thread-safe Python library for parsing and decoding Garmin FIT files. It provides a 1:1 representation of FIT streams, including headers and footers, and supports binary-level manipulation. Includes CLI utilities fitjson for JSON conversion and fittxt for human-readable text dumps, both featuring message filtering capabilities.

Tokens
2.1K
Snippets
8
Records
9
Agent score
53%

What's inside fitdecode

  1. What is fitdecode and how does it differ from fitparse?

    master

    fitdecode is a Python (>= 3.6) library for parsing and decoding FIT files. It is a rewrite of the fitparse_ library designed for improved performance and thread-safety.

    Key features and differences from fitparse:

    • Performance: Faster execution and optimized memory usage.
    • Thread-safety: Objects keep state locally, allowing concurrent reading of multiple streams.
    • Complete Stream Representation: Unlike fitparse, fitdecode does not discard the FIT header or CRC footer, providing a 1:1 representation of the stream. This makes it easier to handle chained (concatenated) FIT files.
    • Flexible CRC Handling: CRC computation and matching are optional. You can match CRC, only compute it, or ignore it entirely for faster reading.
    • Binary Access: Provides optional access to records, headers, and footers in their binary form, enabling binary-level cutting, stitching, and filtering.

  2. Read a FIT file frame by frame

    master

    Use fitdecode.FitReader to iterate through a FIT file. The reader yields different types of frame objects depending on the content of the stream. You can identify the type of frame by checking its frame_type attribute.

    Supported frame types include:

    • fitdecode.FitHeader (FIT_FRAME_HEADER)
    • fitdecode.FitDefinitionMessage (FIT_FRAME_DEFINITION)
    • fitdecode.FitDataMessage (FIT_FRAME_DATA)
    • fitdecode.FitCRC (FIT_FRAME_CRC)

    When frame_type is fitdecode.FIT_FRAME_DATA, the object is a FitDataMessage containing decoded values that can be accessed directly (e.g., via .name).

    import fitdecode

with fitdecode.FitReader('file.fit') as fit:
    for frame in fit:
        if frame.frame_type == fitdecode.FIT_FRAME_DATA:
            # frame is a FitDataMessage object
            print(frame.name)

  3. Install fitdecode via pip

    master

    You can install fitdecode directly from PyPI using pip:

    pip install fitdecode

    Alternatively, you can install from source by cloning the repository:

    git clone git@github.com:polyvertex/fitdecode.git
cd fitdecode
pip install .

  4. Filter FIT messages with the --filter flag

    master

    You can use the --filter (or -f) flag to include or exclude specific FIT messages from the JSON output. This is useful for reducing file size or focusing on specific data types. The filter works by prefixing the message name or global message number with a sign:

    • +name or name: Includes the specified message (default behavior if no other filters are provided).
    • -name: Excludes the specified message.

    If you use a negative filter (e.g., -record), the default policy becomes 'exclude everything except what is explicitly included'.

    # Exclude all 'record' messages
fitjson input.fit --filter "-record"

# Include only 'file_id' messages and exclude 'record' messages
fitjson input.fit --filter "+file_id" --filter "-record"

# Use global message numbers instead of names
fitjson input.fit --filter "-140"

  5. Convert FIT files to JSON or Text using CLI utilities

    master

    fitdecode provides two command-line utilities for inspecting FIT files:

    fitjson

    Converts a FIT file to JSON format.

    fitjson --pretty -o out_file.json in_file.fit

    fittxt

    Converts a FIT file to a human-readable text format for debugging.

    fittxt -o out_file.txt in_file.fit
    fitjson --pretty -o out_file.json in_file.fit
$ fittxt -o out_file.txt in_file.fit

  6. Filter messages in CLI utilities

    master

    Both fitjson and fittxt support a --filter (or -f) option to include or exclude specific message types. This option can be specified multiple times.

    • To include only specific messages: Use the message name (e.g., -f=record).
    • To exclude specific messages: Prefix the message name with a minus sign (e.g., -f=-file_id).

    Examples:

    # Include only RECORD messages:
fitjson -f=record -o out_file.json in_file.fit

# Exclude FILE_ID and EVENT messages:
fitjson -f=-file_id -f=-event -o out_file.json in_file.fit
    fitjson -f=record -o out_file.json in_file.fit
fitjson -f=-file_id -f=-event -o out_file.json in_file.fit

  7. Reference: fitjson CLI flags and arguments

    master

    The fitjson utility accepts the following arguments and options to control the conversion process:

    Arguments:
  FITFILE                Input .FIT file (use - for stdin)

Options:
  --output, -o            File to output data into (defaults to stdout)
  --pretty                Prettify JSON output.
  --nocrc                 Some devices seem to write invalid CRC's, ignore these.
  --nodef                 Do not output FIT local message definitions.
  --nounk                 Do not output unknown FIT messages (e.g. "unknown_140")
  --filter, -f            Message name(s) (or global numbers) to filter-in or out, 
                          depending on sign prefix. Examples: "-record" to exclude 
                          record messages; "+file_id" or "file_id" to include 
                          file_id messages.

  8. Use the fittxt CLI to dump FIT files to text

    master

    The fittxt command-line utility converts .FIT files into a human-readable text format designed for debugging. It provides a structured view of FIT headers, message definitions, and data messages, along with global statistics.

    Basic Usage

    To dump a FIT file to stdout:

    python -m fitdecode.cmd.fittxt input.fit

    To save the output to a specific file:

    python -m fitdecode.cmd.fittxt input.fit -o output.txt

    Filtering Messages

    You can include or exclude specific message types using the --filter (or -f) flag. Use a + prefix (or no prefix) to include a message, and a - prefix to exclude it. You can use message names or global message numbers.

    • Exclude a message type: -f -record (excludes all 'record' messages)
    • Include a specific message: -f file_id (includes only 'file_id' messages)

    Common Flags

    FlagDescription
    -o, --outputFile to output data into (defaults to stdout)
    --nocrcIgnore invalid CRCs (useful for devices with buggy CRC implementations)
    --nodefDo not output FIT local message definitions
    --nounkDo not output unknown FIT messages (e.g. "unknown_140")
    --stripDo not output the extended global stats in the header
    -f, --filterMessage name(s) or global numbers to filter in/out

    Note: Use - for infile to read from stdin.

    python -m fitdecode.cmd.fittxt input.fit -o output.txt -f -record

  9. Convert FIT files to JSON using fitjson

    master

    The fitjson command-line utility allows you to dump the contents of a .FIT file into a JSON format. It decodes the FIT structure, including headers, message definitions, and data messages, into a structured JSON array. By default, it uses StandardUnitsDataProcessor to provide human-readable units.

    # Basic usage (outputs to stdout)
fitjson input.fit

# Output to a file with pretty-printed JSON
fitjson input.fit --output output.json --pretty