Converter TCX para CSV

O Training Center XML foi desenhado pela Garmin para descrever uma sessão de treino. Sua estrutura mostra isso: um `TrainingCenterDatabase` guarda Activities, cada Activity guarda Laps, cada Lap declara duração, distância, valor de calorias, frequência cardíaca média e máxima e um motivo de disparo, e só então guarda uma Track de pontos individuais. A rota é apenas um fluxo registrado entre vários, e possivelmente não o mais importante.

O CSV produzido aqui pega só essa última parte. Todo trackpoint com posição vira uma linha de latitude, longitude, elevação e horário, em ordem, e toda a camada de treino acima é descartada. Se você veio buscando uma rota que consegue plotar ou medir, é um resultado limpo. Se veio buscando o treino, a maior parte do que você queria ficou no arquivo, e o resto desta página é sobre exatamente quais partes.

Um Trackpoint num TCX pode carregar um `<Time>`, uma `<Position>` com latitude e longitude em elementos filhos separados, uma `<AltitudeMeters>`, um total corrido de `<DistanceMeters>`, um `<HeartRateBpm>`, uma `<Cadence>` e um bloco `<Extensions>`. Quatro são lidos: horário, as duas metades da posição e a altitude. Viram as colunas `time`, `latitude`, `longitude` e `elevation`, com uma coluna `type` que sempre diz `track` e uma coluna `name` carregando o esporte da atividade.

A omissão mais provável de surpreender é `<DistanceMeters>`. Está presente na maioria dos trackpoints escritos por um aparelho Garmin, é a leitura do odômetro naquele instante, e não é lida — então o CSV não tem distância acumulada, mesmo que a origem tivesse em cada linha. Recalcular a partir de coordenadas consecutivas dá uma resposta ligeiramente diferente, porque o aparelho mistura dados de roda ou footpod ao seu próprio número, e uma diferença de coordenadas não consegue fazer isso.

Frequência cardíaca é filha direta do Trackpoint, escrita como `<HeartRateBpm><Value>148</Value></HeartRateBpm>`. Cadência é irmã dela. Cadência de corrida, watts e velocidade instantânea ficam um nível mais fundo, num bloco `<Extensions>` usando o namespace de extensão de atividade da Garmin. Todos são valores por amostra sentados ao lado das coordenadas que de fato atravessam.

O motivo de nenhum deles aparecer é que este conversor lê todo formato de GPS através de uma forma compartilhada — um ponto com posição, elevação opcional e horário opcional — e escreve cada saída a partir dessa forma. É o que permite ao mesmo código transformar um TCX em GPX, KML ou tabela sem quatro implementações separadas, e o preço é que qualquer coisa fora desses quatro valores fica invisível para ele. É uma limitação real, não temporária, e é por isso que é declarada aqui em vez de escondida numa ressalva.

Voltas são achatadas. Os trackpoints de cada volta de uma atividade são concatenados numa única sequência contínua de linhas, então doze repetições de quatrocentos metros saem parecendo exatamente um esforço ininterrupto de seis quilômetros. Nada no CSV marca onde uma volta terminou, e nenhuma coluna registra a qual volta uma linha pertencia.

Os resumos vão junto, e são a parte que um treinador mais sentiria falta: `TotalTimeSeconds`, `DistanceMeters`, `MaximumSpeed`, `Calories`, `AverageHeartRateBpm` e `MaximumHeartRateBpm` são todos declarados por volta na origem, e nenhum chega à tabela. Se estrutura de volta é o que você está analisando, leia o TCX diretamente — é XML simples e os elementos de volta ficam perto do topo de cada atividade, o que os torna incomumente fáceis de extrair com um script curto.

Um Trackpoint sem `<Position>` é descartado, e isso responde por quase todo caso em que o CSV tem menos linhas do que o arquivo tem trackpoints. Não é corrupção. Um relógio amostra frequência cardíaca uma vez por segundo independentemente de travamento de satélite, então uma sessão que começa dentro de casa, passa sob uma ponte ou corre por uma rua coberta escreve trackpoints perfeitamente válidos que carregam horário e frequência cardíaca e nenhuma coordenada.

Uma sessão de esteira ou rolo de treino é o caso extremo: todo trackpoint carece de posição, então nada pode ser escrito, e a conversão relata que nenhuma trilha ou ponto de interesse foi encontrado. Essa mensagem é precisa — o arquivo genuinamente não contém geometria — e é o sinal mais claro possível de que uma saída em forma de rota nunca ia funcionar para este treino.

Uma atividade TCX não tem nome. O que tem é um atributo `Sport` no elemento `<Activity>`, e o esquema o restringe a `Running`, `Biking` ou `Other`. Esse valor vira a coluna `name`, repetido em cada linha, porque é o único identificador legível que o formato oferece.

O título que você vê no Garmin Connect ou no Strava — «Intervalos de terça», «Volta para casa» — não está no TCX de jeito nenhum; pertence ao banco de dados da plataforma, não ao export. Então uma pasta de arquivos TCX convertidos um atrás do outro produz tabelas cujas colunas de nome dizem `Running` repetidamente, e distingui-las depois depende dos nomes de arquivo e da coluna `time`, não de nada dentro dos dados.

O elemento `<Time>` é copiado literalmente para a coluna `time` sem reformatar, porque ISO 8601 já é padrão e reescrevê-lo só imporia uma preferência. Aparelhos Garmin costumam escrever UTC com um Z no final, e alguns escrevem frações de segundo, então `2026-03-14T06:41:07.000Z` chega com os milissegundos intactos.

Isso tem dois efeitos práticos. Ordenar pela coluna funciona como texto simples, já que ISO 8601 ordena lexicamente, o que significa que uma tabela mesclada de várias sessões ordena corretamente mesmo numa ferramenta que não reconheceu a coluna como data. E os horários estão em UTC, então uma linha 6:41 é um início 07:41 no inverno da Europa Central — uma diferença grande o bastante para mover uma sessão matinal para o dia anterior quando você agrupa por data.

Se a análise que você tem em mente é sobre frequência cardíaca, potência ou cadência, esta conversão não vai levar você lá, e nenhuma quantidade de pós-processamento recupera valores que nunca foram escritos. O próprio TCX é o caminho mais curto: é XML simples, os elementos são nomeados de forma consistente, e uma dúzia de linhas de Python com `xml.etree` puxa `HeartRateBpm` e `Time` para um dataframe junto com as coordenadas.

A outra opção honesta é a plataforma que produziu o arquivo. Garmin Connect, Strava e TrainingPeaks exportam dados por atividade já com as colunas de sensor achatadas, e seus exports incluem valores que o TCX nem guarda: potência normalizada, carga de treino, os próprios cálculos de zona do aparelho. Converter um TCX é a jogada certa quando você quer a rota; é a jogada errada quando você quer o treino.

`<AltitudeMeters>` é copiado para a coluna de elevação exatamente como o aparelho escreveu: metros, sem arredondamento, sem correção. Num relógio com altímetro barométrico isso é uma leitura de pressão calibrada no início da sessão. Num sem, é a solução de altitude por satélite, que é o número mais ruidoso que um GPS produz e deriva dezenas de metros com o receptor parado.

O número que uma plataforma de treino mostra frequentemente não é esse número. Correção de elevação — buscar cada posição num modelo de terreno e substituir pela altura levantada — é um padrão comum, e produz um perfil mais suave e um ganho total diferente. Nenhum valor está errado; medem coisas diferentes. Então espere uma discrepância ao comparar a tabela convertida com o app, e espere que seja maior num dia ventoso ou quando uma frente passa, porque é exatamente a isso que um barômetro não calibrado responde.

O XML é analisado e as linhas são escritas no seu navegador. Nenhuma requisição carrega o TCX para lugar nenhum, o que dá para confirmar no painel de rede enquanto uma conversão roda, e a página continua funcionando com a conexão desligada depois de carregada.

Isso importa mais para dados de treino do que a extensão do arquivo sugere. Um TCX é um registro minuto a minuto de onde alguém estava, o quanto estava se esforçando e como o coração respondeu, que é dado de saúde em todo sentido que importa e dado de localização por cima disso. Um CSV convertido é a mesma informação numa forma que qualquer pessoa lê num relance, então vale guardar com o mesmo cuidado do original em vez de tratar como um arquivo de rascunho derivado.