Metadata-Version: 2.1
Name: hms-import
Version: 0.2.0
Summary: Uploads encrypted video files and metadata to Tator.
License: MIT
Author: CVision AI, Inc.
Author-email: info@cvisionai.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: natsort (>=8.4.0,<9.0.0)
Requires-Dist: pillow (>=10.0.0,<11.0.0)
Requires-Dist: pynmea2 (>=1.19.0,<2.0.0)
Requires-Dist: tator (>=1.1.0,<2.0.0)
Requires-Dist: tqdm (>=4.65.0,<5.0.0)
Description-Content-Type: text/markdown

# HMS Import

Import utility for encrypted video and metadata files.

# Installation

## From Wheel

This assumes you have [Python 3.9+](https://www.python.org/downloads/) installed and `pip3` is on
your path. With the `hms-import.whl` file in your current directory, run:

```bash
~$ pip3 install ./hms-import.whl
...
~$ hms-import -h
usage: hms-import [-h] {b3-upload,b3-generate-states,o2-upload} ...

Script for importing video and metadata in O2 and B3 formats.

options:
  -h, --help            show this help message and exit

Commands:
  {b3-upload,b3-generate-states,o2-upload}
    b3-upload           Imports video and GPS files from unlocked LUKS-encrypted device
    b3-generate-states  Generates states from GPS files
    o2-upload           Script for uploading raw, encrypted video files.
```

## From Source

This assumes you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), [Python
3.9+](https://www.python.org/downloads/), and
[poetry](https://python-poetry.org/docs/#osx--linux--bashonwindows-install-instructions) installed
already.

```bash
~$ git clone git@github.com:cvisionai/hms.git
...
~$ cd hms/scripts/hms-import
hms-import$ poetry install
...
hms-import$ poetry run hms-import -h
```

# Usage

This script contains two sub-commands: `o2-upload` and `b3-upload`; their usage is described below.
Additional documentation is available by providing the `-h` flag, e.g. `hms-import o2-upload -h`.

## o2-upload

The first step is to set up your `config.ini` file. Start by copying the contents of
[sample_hms-config.ini](./sample_hms-config.ini) included below for reference, and replace the
default values:

```ini
[Local]
# The directory containing the video files for import
Directory=dir1
# The extension of the encrypted video files
MediaExtension=.video
# The extension of the encrypted metadata files
MetadataExtension=.log

[Tator]
# The url to the tator deployment
Host=https://hms.tator.io
# The API token for tator
Token=6485c83cf040deadbeef07b7aea13706
# The integer id of the project to upload the videos to
ProjectId=-1
# The integer id of the media type to create, required if the project has more than one video media type
MediaType=-1
# The integer id of the file type to create for the uploaded encrypted sensor data file
FileType=-1
# The integer id of the image type to create for the trip summary image
SummaryType=-1
# The name of the algorithm to launch upon upload of each trup
AlgorithmName=Decrypt Trip

[Trip]
# The ISO-formatted, timezone aware (if applicable) sail date
SailDate=2023-07-15T19:46:16.671406+00:00
# The ISO-formatted, timezone aware (if applicable) land date
LandDate=2023-07-18T19:46:16.671406+00:00
# The ISO-formatted, timezone aware (if applicable) HDD receipt date
HddDateReceived=2023-07-19T19:46:16.671406+00:00
# The serial number of the hard drive
HddSerialNumber=123ABC
```

Once configured, you can run the import utility:

```bash
$ hms-import o2-upload config.ini
```

### Troubleshooting

If an import fails, the logs have more detail than the console, they can be found in the same folder
the command was run from, with the filename `hms_import.log`. These are rotating logs that cycle
daily (if the log file is not current, it will have an `.MM-DD-YY` extension appended to the
filename) and are kept for up to 7 days, so as to not consume disk space without limit.


## b3-upload

The B3 import process requires two manual steps, the former being `b3-upload`. This sub-command
requires the following arguments:

* `--host` the tator hostname (string)
* `--token` the tator API token (string)
* `--media-type-id` the media type id (integer)
* `--file-type-id` the file type id (integer)
* `--multi-type-id` the multiview type id (integer)
* `--state-type-id` the state type id (integer)
* `--sail-date` the sail date of this trip (ISO-formatted date string)
* `--land-date` the land date of this trip (ISO-formatted date string)
* `--hdd-recv-date` the receipt date of the hard drive (ISO-formatted date string)
* `--hdd-sn` the serial number of the hard drive
* `--directory` the location of the files to upload

Once you have those values, use them to call the script:

```bash
$ hms-import b3-upload \
    --host <TATOR_HOST> \
    --token <TATOR_TOKEN> \
    --media-type-id <id> \
    --file-type-id <id> \
    --multi-type-id <id> \
    --state-type-id <id> \
    --sail-date <date> \
    --land-date <date> \
    --hdd-recv-date <date> \
    --hdd-sn <sn> \
    --directory <path/to/files>
```

