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:
- elimina los espacios en blanco iniciales y finales;
- convierte el nombre a minúsculas;
- elimina los espacios;
- elimina los guiones bajos (
_); - 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.