TKK CSV Injector — Referencia del Formato de Archivo

1. Alcance

Esta especificación define el formato CSV aceptado por el importador de tracks CSV de Trakkit.

Este documento está destinado a desarrolladores y contiene información técnica y especificaciones. No está destinado a servir como la fuente principal de documentación. Para una introducción y pautas generales de uso, consulta la TKK – Documentación General de Trakkit.

Un archivo CSV representa una secuencia de posiciones GPS asociadas a un barco existente. Cada registro debe contener una marca de tiempo, latitud y longitud. Opcionalmente, pueden suministrarse datos de navegación como velocidad, rumbo, viento, orientación, profundidad, temperatura, presión, RPM del motor y elevación.


2. Requisitos del Archivo

Propiedad Requisito
Tipo de archivo CSV de texto
Codificación UTF-8 o UTF-8 con BOM
Separador de campos coma (,), punto y coma (;), barra vertical (|) o TAB
Encabezado Obligatorio
Columnas mínimas 3
Campos obligatorios DATE, LAT, LON
Separador decimal . o ,

El archivo DEBE contener al menos un registro con una fecha válida, latitud y longitud.


3. Archivo Válido Mínimo

DATE;LAT;LON
2026-08-14 08:00:00;43.69520;7.28460
2026-08-14 08:05:00;43.70110;7.29130
2026-08-14 08:10:00;43.70840;7.29880

4. Coincidencia de Encabezados

Los nombres de encabezado no distinguen entre mayúsculas y minúsculas.

Antes de comparar un encabezado, el importador:

  1. elimina los espacios en blanco iniciales y finales;
  2. convierte el nombre a minúsculas;
  3. elimina los espacios;
  4. elimina los guiones bajos (_);
  5. elimina los guiones (-).

Por lo tanto, los siguientes nombres de encabezado son equivalentes:

SpeedOverGround
speed over ground
speed_over_ground
speed-over-ground
SPEEDOVERGROUND

Cada nombre de campo canónico es, por sí mismo, un encabezado válido.


5. Campos Obligatorios

DATE

Marca de tiempo de la posición GPS (UTC implícito si no hay zona horaria)

Nombres de encabezado aceptados:

DATE
date
ts
timestamp
datetime
time
horaire
utc

LAT

Latitud.

Nombres de encabezado aceptados:

LAT
lat
latitude

LON

Longitud.

Nombres de encabezado aceptados:

LON
lon
long
longitude
lng

Un registro se rechaza si cualquiera de DATE, LAT o LON no puede analizarse.


6. Campos de Navegación Opcionales

Campo Descripción Alias aceptados
AWS Velocidad del Viento Aparente aws, apparentwindspeed, windspeedapparent
AWA Ángulo del Viento Aparente awa, apparentwindangle, windangleapparent
COG Rumbo sobre el fondo (COG) cog, courseoverground
SOG Velocidad sobre el fondo (SOG) sog, speedoverground
TWA Ángulo del Viento Verdadero twa, truewindangle
TWS Velocidad del Viento Verdadero tws, truewindspeed
MTW Temperatura del Agua mtw, watertemperature, tempwater, seatemperature
MTA Temperatura del Aire mta, airtemperature, tempair
HDG Orientación (Heading) hdg, heading
AWSMIN Velocidad Mínima del Viento Aparente awsmin, minaws, apparentwindspeedmin
AWSMAX Velocidad Máxima del Viento Aparente awsmax, maxaws, apparentwindspeedmax
TWD Dirección del Viento Verdadero twd, truewinddirection
CTW Rumbo a través del agua (CTW) ctw, coursethroughwater
MBP Presión Barométrica mbp, baropressure, pressure, pressurebaro, barometer
STW Velocidad a través del agua (STW) stw, speedthroughwater
DEPTH Profundidad del Agua depth, profondeur, waterdepth, sonde
RPM RPM del Motor rpm, enginerpm, motorrpm
ELEV Elevación / Altitud elev, elevation, alt, altitude

Todos los campos enumerados arriba se aceptan para la importación a la base de datos.

Un valor opcional vacío o no numérico se almacena como valor nulo y no provoca que el registro sea rechazado.


7. Formatos de Fecha y Hora

DATE acepta marcas de tiempo Unix, marcas de tiempo ISO 8601 y varios formatos de fecha convencionales.

7.1 Marca de Tiempo Unix

Época Unix en segundos:

1786694400

Época Unix en milisegundos:

1786694400000

Se reconocen cadenas de marcas de tiempo numéricas que contengan de 10 a 17 dígitos.

Los valores mayores que 10^12 se tratan como milisegundos.

7.2 ISO 8601

Ejemplos:

2026-08-14T08:00:00Z
2026-08-14T08:00:00+00:00
2026-08-14T10:00:00+02:00

Los valores con zona horaria se convierten a UTC.

Las marcas de tiempo ISO sin información de zona horaria se interpretan como UTC.

7.3 Formatos Convencionales

Se aceptan los siguientes formatos:

YYYY-MM-DD HH:MM:SS
YYYY-MM-DD HH:MM
YYYY/MM/DD HH:MM:SS
YYYY/MM/DD HH:MM
YYYY-MM-DD
YYYY/MM/DD
DD/MM/YYYY HH:MM:SS
DD/MM/YYYY HH:MM
DD/MM/YYYY
YYYYMMDD HHMMSS
YYYYMMDD HHMM
YYYYMMDD

Ejemplos:

2026-08-14 10:35:12
2026-08-14 10:35
2026/08/14 10:35:12
14/08/2026 10:35:12
14/08/2026 10:35
14/08/2026
20260814 103512
20260814 1035
20260814

Las fechas convencionales sin información de zona horaria se interpretan como UTC.


8. Valores Numéricos

Los campos numéricos aceptan tanto un punto como una coma como separador decimal, pero esto NO DEBE entrar en conflicto con el separador de campos.

Los campos pueden protegerse con comillas dobles (").

Ejemplos válidos:

5.7
5,7
"43.69520"
43,69520

9. Coordenadas

La latitud y la longitud deben ser numéricas.

Se aceptan coordenadas negativas.

Ejemplo:

DATE;LAT;LON
2026-08-14 08:00:00;32.37000;-64.64000

Las coordenadas se redondean a cinco decimales antes de almacenarse.

Ejemplo:

43.6952347 -> 43.69523
7.2846128  -> 7.28461

10. Valores Faltantes

Los campos obligatorios deben contener valores válidos.

No válido:

DATE;LAT;LON
2026-08-14 08:00:00;43.69520;

Los campos opcionales pueden estar vacíos:

DATE;LAT;LON;SOG;COG;AWS
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;13.2
2026-08-14 08:05:00;43.70110;7.29130;;85;
2026-08-14 08:10:00;43.70840;7.29880;6.0;;

Un valor numérico opcional no válido se trata como nulo.


11. Columnas Desconocidas

Las columnas que no coincidan con un campo o alias reconocido se ignoran para la importación de datos de navegación.

Ejemplo:

DATE;LAT;LON;COMMENT
2026-08-14 08:00:00;43.69520;7.28460;Departure

COMMENT es un campo desconocido.

Los nombres de encabezado desconocidos son registrados por el importador en:

fields_unknown.txt

El archivo se mantiene en el mismo directorio que el CSV importado.


12. Validación del Archivo

Un archivo se acepta solo si se cumplen todas las condiciones siguientes:

Comprobación Requisito
El archivo existe Obligatorio
No vacío Obligatorio
Detección de binario Debe ser texto
Codificación Debe poder leerse como UTF-8
Delimitador coma (,), punto y coma (;), barra vertical (|) o TAB sin conflicto
Encabezado Al menos 3 columnas
Campos obligatorios DATE, LAT, LON deben resolverse mediante nombres canónicos o alias
Data Al menos un registro debe contener una fecha válida, latitud y longitud

Un archivo que no contenga ningún registro GPS válido se rechaza.


13. Validación de Registros

Para cada registro CSV:

Condición Resultado
DATE + LAT + LON válidos Registro aceptado
DATE no válido Registro rechazado
LAT no válida Registro rechazado
LON no válida Registro rechazado
Campo opcional no válido Registro aceptado; campo almacenado como nulo
Campo opcional vacío Registro aceptado; campo almacenado como nulo

14. Formatos de Ejemplo

14.1 Solo Posición

DATE;LAT;LON
2026-08-14 08:00:00;43.69520;7.28460
2026-08-14 08:05:00;43.70110;7.29130

14.2 Velocidad y Rumbo GPS

DATE;LAT;LON;SOG;COG
2026-08-14 08:00:00;43.69520;7.28460;5.4;82
2026-08-14 08:05:00;43.70110;7.29130;5.7;85

14.3 GPS y Viento Aparente

DATE;LAT;LON;SOG;COG;AWS;AWA
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;13.2;41
2026-08-14 08:05:00;43.70110;7.29130;5.7;85;14.1;38

14.4 Nombres de Encabezado Largos

datetime;latitude;longitude;speedoverground;courseoverground;apparentwindspeed;apparentwindangle;truewindspeed;truewindangle;truewinddirection
2026-08-14T08:00:00Z;43.69520;7.28460;5.4;82;13.2;41;11.5;36;225
2026-08-14T08:05:00Z;43.70110;7.29130;5.7;85;14.1;38;12.0;34;228

14.5 Variantes de Encabezado Legibles por Humanos

Timestamp;Latitude;Longitude;Speed Over Ground;Course-Over-Ground;Apparent_Wind_Speed
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;13.2
2026-08-14 08:05:00;43.70110;7.29130;5.7;85;14.1

14.6 Comas Decimales

DATE;LAT;LON;SOG;COG
14/08/2026 08:00;43,69520;7,28460;5,4;82
14/08/2026 08:05;43,70110;7,29130;5,7;85

14.7 Marcas de Tiempo Unix

timestamp;lat;lon;sog;cog
1786694400;43.69520;7.28460;5.4;82
1786694700;43.70110;7.29130;5.7;85

14.8 Datos de Navegación Extendidos

DATE;LAT;LON;SOG;COG;STW;HDG;AWS;AWA;TWS;TWA;TWD;MTW;MTA;MBP;DEPTH;RPM;ELEV
2026-08-14 08:00:00;43.69520;7.28460;5.4;82;5.1;80;13.2;41;11.5;36;225;24.7;28.1;1013.2;18.4;1850;0
2026-08-14 08:05:00;43.70110;7.29130;5.7;85;5.4;83;14.1;38;12.0;34;228;24.8;28.2;1013.1;19.1;1870;0

16. Lote de Importación

Si se aceptan al menos dos registros, el importador crea un lote con:

name = Uploaded from CSV

La hora de inicio del lote es la marca de tiempo del registro aceptado más temprano.

La hora de fin del lote es la marca de tiempo del registro aceptado más tardío.

Todos los registros aceptados de una importación CSV comparten el mismo identificador de lote.