[Feature request] Documentation for dataset and directory structure

[connorlee77]

Currently, the dataset is given with no documentation on what each folder contains. Can we add to the README.md a short description of what the data in each folder represents, and if its used in the paper or not? This would allow for students and researchers to use this dataset without trying to match back and forth between the paper/exploratory github code and the dataset (which currently has a bit of educated guesswork involved).

For example, right now, I don't know what the difference is between the lidar_hdl64_strongest and lidar_hdl64_strongest_stereo_left. Likewise, gated_full_rect and gatedX_rect. This documentation would elucidate these types of questions.

I think a good method to document this would simply be a table format like this:

Folder	Used for Training	Used for Testing	Description
cam_stereo_left	yes	yes	8-bit RGB images captured from the left stereo cameras. cam_stereo_left_lut is derived from this...
fir_axis	no	no	8-bit Thermal infrared images
gated0_rect	yes	yes	gated infrared images. Different from gated1_rect, gated2_rect and gated_full_rect in these ways: ....
...	...	...	...
FOLDER_X	?	?	Description of FOLDER_X

If any of the author's would be interested in spending 15-20 min to guide me through this dataset, I would be more than happy to submit a PR for this addition myself.

[MartinHahner]

What is used in training/testing does not depend on the folder, but on the IDs provided in the splits folder. @MarioBijelic: I agree that a table with a short description would indeed help for a quicker and easier "onboarding".

I used the dataset viewer (and its code) to familiarize myself with the dataset. It has the potential to answer many if not all your questions.

[connorlee77]

Right, I saw that the splits are given in its respective folder. Yeah, I agree that the dataset viewer is helpful to get to know the dataset.

My main point of confusion is determining the folders where the actual input data to the model are drawn from. There's data available as 8-bit and 16-bit images. Which ones were actually used for training?

Also, what's the difference between gated_full_rect, and gated_full_acc_rect?

[MarioBijelic]

Hi guys @connorlee77 @MartinHahner ,

I added a detailed explanation for each folder. Happy to hear about your feedback. The folders contain all samples independent of the split. The split indices given in the split folder as already correctly mentioned by @MartinHahner.

The difference between gated_full_rect and gated_full_acc_rect is the type how they are collected. In gated_full_acc_rect all gated slices are overlaid manually this adds a small time delay between single slices. In gated_full_rec the overlay is captured during one acquisition made by the camera. This can only be done if the the total laser power is not exceeded. Hence, not for each index a gated_full_rec capture is available.

Best

[connorlee77]

Sweet this is great and should definitely help users onboard more quickly! Thanks for being on top of it!

[manonthegithub]

@MarioBijelic @connorlee77 @MartinHahner hi!

I have seen the description of the folders but still can not get the difference between gated_full_rect8 (8-bit rectified bitshifted NIR gated camera image with joint slices from a single capture.) and gated_full_acc_rect8 (8-bit rectified bitshifted NIR gated camera image with overlayed gated slices from gated_8bit.). Why does gated_full_rect8 contain only 4841 files, but gated_full_acc_rect8 - 12997 files.

Thank you for the help!

[connorlee77]

It looks like the frames in gated_full_rect8 were captured as a single frame at a particular timestamp. These are only available when operating under the power constraints, so there are less frames captured.

In contrast, the frames from gated_full_acc_rect8 are created by overlaying the associated slices (frames) from gatedX_rect8, where each slice may be slightly offset temporally from each other.

[manonthegithub]

@connorlee77 thank you! Looks like that...