Geo::FIT - Decode Garmin FIT files
use Geo::FIT;
Create an instance, assign a FIT file to it, open it:
my $fit = Geo::FIT->new(); $fit->file( $fname ); $fit->open or die $fit->error;
Register a callback to get some info on where we've been and when:
my $record_callback = sub { my ($self, $descriptor, $values) = @_; my $time= $self->field_value( 'timestamp', $descriptor, $values ); my $lat = $self->field_value( 'position_lat', $descriptor, $values ); my $lon = $self->field_value( 'position_long', $descriptor, $values ); print "Time was: ", join("\t", $time, $lat, $lon), "\n" }; $fit->data_message_callback_by_name('record', $record_callback ) or die $fit->error; my @header_things = $fit->fetch_header; 1 while ( $fit->fetch ); $fit->close;
Geo::FIT is a Perl class to provide interfaces to decode Garmin FIT files (*.fit).
Geo::FIT
The module also provides a script to read and print the contents of FIT files (fitdump.pl), a script to convert FIT files to TCX files (fit2tcx.pl), and a script to convert a locations file to GPX format (locations2gpx.pl).
creates a new object and returns it.
Returns a copy of a Geo::FIT instance.
clone() is experimental and support for it may be removed at any time. Use with caution particularly if there are open filehandles, it which case it is recommended to close() before cloning.
clone()
close()
It also does not return a full deep copy if any callbacks are registered, it creates a reference to them. There is no known way to make deep copies of anonymous subroutines in Perl (if you know of one, please make a pull request).
The main use for c<clone()> is immediately after new(), and file(), to create a copy for later use.
new()
file()
returns a string representing the .FIT profile version on which this class based.
returns the name of a .FIT file. Sets the name to $filename if called with an argument (raises an exception if the file does not exist).
opens the .FIT file.
reads .FIT file header, and returns an array of the file size (excluding the trailing CRC-16), the protocol version, the profile version, extra octets in the header other than documented 4 values, the header CRC-16 recorded in the header, and the calculated header CRC-16.
reads a message in the .FIT file, and returns 1 on success, or undef on failure or EOF. fetch_header() must have been called before the first attempt to fetch() after opening the file.
1
undef
fetch_header()
fetch()
If a data message callback is registered, fetch() will return the value returned by the callback. It is therefore important to define explicit return statements and values in any callback (this includes returning true if that is the desired outcome after fetch()).
returns an error message recorded by a method.
CRC-16 calculated from the contents of a .FIT file.
CRC-16 attached to the end of a .FIT file. Only available after all contents of the file has been read.
number of octets after CRC-16, 0 usually.
register a function callback function which is called when a data message with the messag number message number is fetched.
register a function callback function which is called when a data message with the name message name is fetched.
returns real data type attributes for a C's union like field.
Given a data message descriptor ($descriptor), returns the list of fields described in it. If keep_unknown is set to true, unknown field names will also be listed.
keep_unknown
Given a data message descriptor ($descriptor) and a corresponding data array reference of values ($values), returns the list of fields whose value is defined. Unknow field names are never listed.
Returns the value of the field named $field (a string).
The other arguments consist of the data message descriptor ($descriptor, a hash reference) and the values fetched from a data message ($values, an array reference). These are simply the references passed to data message callbacks by fetch(), if any are registered, and are simply to be passed on to this method (please do not modifiy them).
For example, we can define and register a callback for file_id data messages and get the name of the manufacturer of the device that recorded the FIT file:
file_id
my $file_id_callback = sub { my ($self, $descriptor, $values) = @_; my $value = $self->field_value( 'manufacturer', $descriptor, $values ); print "The manufacturer is: ", $value, "\n" }; $fit->data_message_callback_by_name('file_id', $file_id_callback ) or die $fit->error; 1 while ( $fit->fetch );
Converts the value parsed and returned by field_value() back to what it was when read from the FIT file and returns it.
field_value()
This method is mostly for developers or if there is a particular need to inspect the data more closely, it should seldomly be used. Arguments are similar to field_value() except that a single value $value is passed instead of an array reference. That value corresponds to the value the former method has or would have returned.
As an example, we can obtain the actual value recorded in the FIT file for the manufacturer by adding these lines to the callback defined above:
my $as_read = $self->field_value_as_read( 'manufacturer', $descriptor, $value ); print "The manufacturer's value as recorded in the FIT file is: ", $as_read, "\n"
The method will raise an exception if $value would have been obtained by field_value() via an internal call to switched(). In that case, the type name or the original array reference of values that was passed to the callback must be provided as the last argument. Otherwise, there is no way to guess what the value read from the file may have been.
switched()
This method is now deprecated and is no longer supported. Please use field_value() instead.
converts value to a (hopefully) human readable form.
This method is now deprecated and is no longer supported. Please use field_value_as_read() instead.
field_value_as_read()
converts a human readable representation of a datum to an original form.
sets the flag which of GMT or local timezone is used for date_time type value conversion. Defaults to true.
date_time
sets unit conversion table for unit.
wrapper methods of unit_table() method. semicircle_to_deg() defaults to true.
unit_table()
semicircle_to_deg()
closes opened file handles.
Returns a string representation of the profile version used by the device or application that created the FIT file opened in the instance.
fetch_header() must have been called at least once for this method to be able to return a value, will raise an exception otherwise.
The following functions are provided. None are exported, they may be called as Geo::FIT::message_name(20), Geo::FIT::field_name('device_info', 4) Geo::FIT::field_number('device_info', 'product'), etc.
Geo::FIT::message_name(20)
Geo::FIT::field_name('device_info', 4)
Geo::FIT::field_number('device_info', 'product')
returns the message name for message spec or undef.
returns the message number for message spec or undef.
returns the field name for field spec in message spec or undef.
returns the field index for field spec in message spec or undef.
Following constants are exported: FIT_ENUM, FIT_SINT8, FIT_UINT8, FIT_SINT16, FIT_UINT16, FIT_SINT32, FIT_UINT32, FIT_SINT64, FIT_UINT64, FIT_STRING, FIT_FLOAT16, FIT_FLOAT32, FIT_UINT8Z, FIT_UINT16Z, FIT_UINT32Z, FIT_UINT64Z.
FIT_ENUM
FIT_SINT8
FIT_UINT8
FIT_SINT16
FIT_UINT16
FIT_SINT32
FIT_UINT32
FIT_SINT64
FIT_UINT64
FIT_STRING
FIT_FLOAT16
FIT_FLOAT32
FIT_UINT8Z
FIT_UINT16Z
FIT_UINT32Z
FIT_UINT64Z
Also exported are:
numbers representing base types of field values in data messages.
the maximal number representing base types of field values in data messages.
length of a .FIT file header.
When fetch method meets a definition message, it creates a hash which includes various information about the corresponding data message. We call the hash a data message descriptor. It includes the following key value pairs.
fetch
in a global .FIT profile.
local_message_type
necessarily.
message_number
message_name
only if the message is documented.
callback
of a callback function and callback data, only if a callback is registered.
endian
of multi-octets data in this message, where 0 for littel-endian and 1 for big-endian.
template
used to convert the binary data to an array of Perl representations.
i_
of the value(s) of the field named field name.
o_
c_
of the field named field name.
s_
of whole the field named field name in binary data.
a_
of attributes of the field named field name.
t_
only if the type of the value of the field named field name has a name.
T_
representing base type of the value of the field named field name.
N_
representing index of the filed named field name in the global .FIT profile.
I_
representing the invalid value of the field named field name, that is, if the value of the field in a binary datum equals to this number, the field must be treated as though it does not exist in the datum.
endian_converter
used for endian conversion.
message_length
in octets.
array_length
of Perl representations.
When fetch method meets a data message, it calls a callback function registered with data_message_callback_by_name or data_message_callback_by_num, in the form
data_message_callback_by_name
data_message_callback_by_num
The return value of the function becomes the return value of fetch. It is expected to be 1 on success, or undef on failure status.
Fields in devloper data are given names of the form developer data index_field definition number_converted field name, and related informations are included data message descriptors in the same way as the fields defined in the global .FIT profile.
_
Each converted field name is made from the value of field_name field in the corresponding field description message, after the following conversion rules:
field_name
ord()
If your perl lacks 64bit integer support, you need the module Math::BigInt.
Math::BigInt
Nothing in particular so far.
fit2tcx.pl, fitdump.pl, locations2gpx.pl, Geo::TCX, Geo::Gpx.
No bugs have been reported.
Please report any bugs or feature requests to bug-geo-gpx@rt.cpan.org, or through the web interface at http://rt.cpan.org.
bug-geo-gpx@rt.cpan.org
Originally written by Kiyokazu Suto suto@ks-and-ks.ne.jp with contributions by Matjaz Rihtar.
suto@ks-and-ks.ne.jp
This version is maintained by Patrick Joly <patjol@cpan.org>.
<patjol@cpan.org>
Please visit the project page at: https://github.com/patjoly/geo-fit.
1.10
Copyright 2022, Patrick Joly patjol@cpan.org. All rights reserved.
patjol@cpan.org
Copyright 2016-2022, Kiyokazu Suto suto@ks-and-ks.ne.jp. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install Geo::FIT, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Geo::FIT
CPAN shell
perl -MCPAN -e shell install Geo::FIT
For more information on module installation, please visit the detailed CPAN module installation guide.