How do I repair a corrupt Ladybug stream file?

Applicable products

Ladybug6

Ladybug5+

Overview

Sometimes a Ladybug stream file can become corrupted due to errors in the header. When this happens LadybugCap Pro and the stream repair utility are unable to read the stream file. 

There are configuration options to reduce the likelihood of a stream file being corrupted. Depending on the issue, there may be methods to recover a corrupted file.

Ladybug Stream File Format

Steam File Signature

Every Ladybug stream file starts with a signature. This signature uniquely identifies the file as a Ladybug stream file.

Stream File Header

The stream header structure begins immediately after the file header at offset 16 from the beginning of the file. It contains the information defined by LadybugStreamHeadInfo in ladybug.h. The byte order of this data block is little endian.

The image index table between 0x03F0 and 0x0BF0 is used to locate the keyframes of the stream. Using this table can speed up image searching. The value of K (offset 0x0090) means that the index table contains the offset values for every Kth image. The offset values are relative to the beginning of the stream file. For example, if K = 50, the value of 'Image index [5]' is the offset of image 250 (K * 5 = 250). It is the location of image 250 relative to the first byte of the stream file.

For more information, please see your Ladybug camera's Technical Reference Manual, Appendix B Stream File Format.

Preventing a Corrupt Recording

There are various reasons that can cause a Ladybug stream file recording to be corrupted, such as an unstable connection, electromagnetic or noise interference, or a sudden light intensity change.

There are some settings that can help prevent corrupt files.

1. In LadybugCapPro, open the LadybugCapPro Options dialog.

2. Under JPEG Integrity:

• Disable Save incomplete JPEGs to stream file
• Enable Warn when incomplete JPEGs are detected

This feature is available from the Ladybug SDK version 1.18.0.65 and later. When enabled, if a corrupted JPEG image is detected, a warning window pops up during the recording. To avoid missing frames, go back and re-record the data if a warning window pops up.

Another way to prevent corruption of files is to add an extra loop in your code to purge the first ten frames before beginning a recording.

LadybugImage image;                                   
    for (int i = 0; i < 10 && error != LADYBUG_OK; i++)
    {                                                  
        printf(".");                                   
        error = ::ladybugGrabImage(context, &image);   
    }                                                  

Repairing a Corrupt Stream File

Verify the File has Data

If a stream file is unreadable in LadybugCapPro you can use a hex editor to open the file and check its contents. Our example screens are using HxD Freeware Hex Editor and Disk Editor.

If the stream file still has data, there may be a way to recover the file.

But if the corrupted file only contains '0s' - no data content - the stream file is empty and cannot be recovered.

Use the Stream File Repair Utility

The Stream File Repair Utility attempts to repair stream files that may have become corrupted. It is located under C:\Program Files\Teledyne\Ladybug\bin64

You can use “--help” to show help messages.

Try to fix a corrupted stream file by specifying the path of your corrupted stream file using --input, and using the --verbose and --attempt-repair flags:
ladybugStreamRepairUtility.exe --input "*location of stream file*" --verbose --attempt-repair

Remove the First Frame

If a stream file is unreadable it may be possible to recover it by removing the first frame.

From the bin/bin64 folder of LadybugCap Pro, run ladybugStreamCopy with the following arguments:

<C:\*location of stream file*> <C:\*location of copy destination*> default 1

This copies from frame 1 to the end of the file and leaves out frame 0 (the first frame).

Contact support if needed.