Add README.md

README.md

@@ -0,0 +1,47 @@
+# DecodeHIR
+
+This repository provides a basic script to read the different parts of .HIR
+files produced by the Seek Shot thermal camera.
+
+The `decode_hir.py` script will load the image from a file given on the command
+line and display the visual and thermal images using `matplotlib`.
+
+## File format documentation
+
+An .HIR file consists of multiple sections. The following could be identified and decoded so far:
+
+1. A JPEG _screenshot_ of the camera display at the time when the picture was taken. This is the only official/obvious part of the file.
+2. The raw thermal data.
+3. The visual image.
+
+### Thermal Image
+
+The thermal data starts after the JPEG screenshot, with some metadata/padding in between. The start position can be calculated as follows:
+
+```
+THERMAL_DATA_START = (JPEG_LENGTH & 0xFFFFF000) + 0x2000
+```
+
+It is encoded as a series of little-endian 16-bit (unsigned) values, one for every pixel of the thermal sensor. The sensor resolution of the Seek Shot is 206x156.
+
+The 16-bit values can be converted to °C using the following formula:
+
+```
+temp_degC = raw_value / 64 - 40
+```
+
+### Visual Image
+
+The visual image has a resolution of 1440x1080 pixels and is likely encoded as YCbCr (maybe another variant of YUV). The chroma components (Cb and Cr) are undersampled and only have half the width and height of the luma component Y.
+
+All components are stored uncompressed as 8-bit unsigned values. Each value represents one pixel. The 1440*1080 = 1555200 bytes of luma data Y are stored first, followed by 388800 bytes of chroma data for Cb and then Cr.
+
+For the Seek Shot, the visual image data starts exactly 0x10000 bytes after the thermal data:
+
+```
+VISUAL_DATA_START = THERMAL_DATA_START + 0x10000
+```
+
+The script convert the YCbCr values to RGB according to ITU-R BT.709. See the `ycbcr2rgb()` function for the calulation.
+
+The conversion might still be the wrong one, as the resulting images have quite a strong blue tint, but at least the concept is proven.