H4VAPP is a tool that bulk converts Lightfield images (aka Leia Image Format or H4V images). The app may also be used with MPO files and images from Google Camera or Apple iPhone.

Document Shortcuts:

• click: installing software
• click: installing license
• click: removing quarantine
• click: Allow system policy
• click: System Requirements

Introduction

Primary features include:

• Extract individual Left/Right JPEG images
• Extract Depth Maps (if available in image)
• Convert images to SBS (aka 'Pro SBS 4K' or 2x1) from Lightfield images
• Convert images to experimental Quad (aka 2x2) images

Additional functions:

• Set EXIF artist data and copyright information
• Set or modify GPS location
• Add a watermark (either text or image)
• Resize Leia Image Format's embedded 'right' image to 4K
• Reduce resolution/size of JPEG images

Background

RED Hydrogen One's camera has two capture modes:

• Lightfield: The default camera mode captures Left and Right Image as 4K JPEG, and the Right is stored as either XMP 'meta data' or a secondary image (MPO). The stored Right Image in XMP is reduced to 1K
• Pro SBS 4K: Left and Right Image as 4K JPEG 'side by side'

There is a third format that can be viewed on the LitByLeia display on RED Hydrogen however:

- Quad: These images are displayed directly with NO post-processing by Leia software. A Quad has a top left, top right, bottom left, and bottom right image. When an image is converted to Quad by H4VAPP, each part of the image has 'HD' (1K) with a total resolution of 7680 x 2160.

Depending on the version of the Camera app on Hydrogen One (aka HoloCam), these images may or may not include standard metadata like Artist, Copyright or GPS location.

I had a desire to shoot in Pro 4K SBS mode for more flexibility with my images, but it's not great for sharing images because people will see a double image.

To correct that problem I wrote H4VAPP, which let's you shoot in the default Lightfield capture mode and extract an SBS when you desire.

Stuff I must write here

It's now available as an 'early beta' from here:

https://h4vapp.com

Currently it's for MacOS Terminal/CLI only. Later in 2023 or early 2024 there will be an easy to use GUI (right click in the Finder) and then later a Windows port.

When the app releases after Beta testing, it will be paid software. The app will cost under US$50. There will probably be an 'early adopter' special discount price. We are a small company (less than 10 people) but with offices in Australia, Germany, UK and New York, USA.

The Future

There is still a lot of functionality to add, but I wanted to get what I've written out to the community now. I know I want to be sharing images taken on RED Hydrogen One, and maybe some of you do too. Here are some features on the roadmap:

• An easy to use 'right click' plugin for the MacOS Finder
• Remove the current requirement of creating left and right images every time
• Convert Quad images to SBS and Lightfield
• Extract each quadrant individually from a Quad
• Better Quad images: currently the app offers L+R/L+R, and the results aren't very good.
• Apply watermarks to SBS and Quad images
• Some kind of steganography (but not Digimarc)
• Recursive directory processing
• Windows 8.1/10 support

This is BETA TEST SOFTWARE

Beta test software is exactly that - there could be bugs, that include the possibility that this program may delete or corrupt files on your disk, or any disk attached to your computer. All editions of the beta test software have a hardcoded expiration date of May 1st, 2021.

Obviously we try really hard to make sure it doesn't do anything nearly that catastrophic - but it's a possibility. These things listed below would all be bugs, and I'm not aware of any problems like this, but this is the sort of bug you could more commonly expect from beta test software:

• The app may crash
• The app may overwrite a file in the conversion process, with a different name to the source or destination
• The app may output files at a lower quality than the original images
• The input file may become corrupted or damaged

Again, I want to be clear - it shouldn't do any of those things. But many backups make happy testers.

Getting started with H4VAPP

1. Before your first use, copy h4vappcmd to your 'HOME' directory on your Mac.
2. On your Mac, start the 'Terminal' app from Applications->Utilities.
3. You're now ready to run the below commands.

Installing Software

Download the installer from this web site and open it on your mac

Drag the h4vappcmd and ffmpg applications to a place of your choosing, eg: your home folder.

You will need to use System Preferences to allow the app to run:

Alternatively you can use this command line technique to remove the quarantine flag.

You will also need to override system policy:

Finally, you may also need to allow full disk access (no image of this setting at this time).

Installing License

The beta test version requires a simple license that will expire in 30 days.

Run this simple command to activate the license:

sudo ~/h4vappcmd --license simple

If you don't want to run 'sudo' then you can create a directory/folder named "/Library/Application Support/com.march-hare.h4vappcmd/" with permissions 0777. In that directory, create a file named named "License”, i.e.: "/Library/Application Support/com.march-hare.h4vappcmd/License" with permissions 0666. This file should contain your license key. Obtain the license key by running this command:

~/h4vappcmd --license simple

Unable to set license key, create the file "...md/License" manually:

License2010=QF0OwkL7OvfS4JDOWcD....zDeLxNbLoK+ckLprrIPNPYdnHH+Aw==

Some beta testers will see this error:

zsh: killed ~/h4vappcmd

zsh: segmentation fault ~/h4vappcmd

If you see this error, then the installation is incomplete - go back and use System Preferences to allow the app to run.

The beta test version comes with 30 day license. If you need an extension on your trial, please email us at hydrogen@4vmail.com for an extension key.

Examples of how to use H4VAPP

Convert Lightfield Image

The core feature of the app is to convert a Lightfield JPEG into separate images (left image, right image, and extract depth maps if available) and also an SBS image where the left and right images are 'side by side'.

~/h4vappcmd ~/Documents/Camera/IMG_20200706_08410867.jpg

The input file can be any of:

• Lightfield image [with the Right HD (1K) Image stored as base 64 encoded meta data]
• Lightfield image [with the 4K Right image stored as MPO]
• Fuji MPO
• Google Camera [with the Right Image stored as base 64 encoded meta data]
• Google Camera [with the Right image and depth map stored as MPO]

All the encoded images are exported separately, plus an SBS of the left/right image.

e.g.: the above command with a newer Leia Image Format file would generate:

IMG_20200706_08410867_2x1.jpg <-- SBS + xmp

IMG_20200706_08410867_1mpo.jpg <-- left image + xmp

IMG_20200706_08410867_2mpo.jpg <-- left depth image + xmp

IMG_20200706_08410867_3mpo.jpg <-- right image + xmp

IMG_20200706_08410867_4mpo.jpg <-- right depth image + xmp

IMG_20200706_08410867_left.jpg <-- left image (including any ICC Profile)

These files will each contain the original XMP metadata, but may not contain non-XMP meta data such as ICC profile.

Re-do the conversion or overwrite

If the target image already exists on disk, it will not be overwritten:

./h4vappcmd IMG_20200706_08410867.jpg

file already exists, abort (use --overwrite to ignore)

To allow you to re-run the same conversion, use the '--overwrite' option:

./h4vappcmd --overwrite IMG_20200706_08410867.jpg

Convert SBS images to Lightfield (two files, one with 4K+4K and one with 4K+1KHD)

The second most basic thing you can do, is to convert an SBS image [where you have two 4K images 'side by side'] to a Lightfield image [with the 4K LEFT image, and the Right HD Image stored as metadata]. We create two Lightfield images, one with 4K meta data, and one with 1K meta data. We've tested both with Hydrogen One, and they both work OK.

~/h4vappcmd --overwrite ~/Documents/Camera/IMG_20181202_18184044_2x1.jpg

Note: We do NOT currently provide a way to create the new Leia Image Format files from SBS files [with the Right image stored as MPO]. Since SBS files do NOT include depth maps, we would need to 'generate' a depth map for this to be a true 'Leia Image Format' Lightfield image, but the algorithm we would use would not be the same as the one Leia uses, resulting in quite a lot of confusion. If there is a demand for these files without the depth data, then we may add that function in future.

Set Copyright and Artist

You'll want to store your copyright info into the EXIF data of the photo. Store it in H4VAPP's preferences so you can easily apply it later:

~/h4vappcmd --copyright="Copright (C) 2020 March Hare Software LLC"

Ditto, the 'artist' info:

~/h4vappcmd --artist="Arthur Barrett"

To use it when creating an H4V image from 'Pro Mode':

~/h4vappcmd --copyright --artist IMG_20181202_18184044_2x1.jpg

To use it when creating an 'Pro Mode' image from H4V:

~/h4vappcmd --copyright --artist IMG_20181202_18184044.jpg

Apply a text watermark

You can write text as a watermark on your image. The easiest way is to store a default string and then use it for subsequent conversions.

Register your watermark:

~/h4vappcmd --txtwatermk="Copyright 2020 Arthur Barrett"

To use it when creating an H4V image from 'Pro Mode':

~/h4vappcmd --txtwatermk IMG_20181202_18184044_2x1.jpg

To use it when creating an 'Pro Mode' image from H4V:

~/h4vappcmd --txtwatermk IMG_20181202_18184044.jpg

Apply an image watermark

You can use an image as a watermark (10%) or you can use an image and an alpha mask.

Using a single image:

~/h4vappcmd --watermkimg="watermark.jpg" IMG_20181202_18184044.jpg

Using an image and alpha:

~/h4vappcmd --watermkimg="watermark.jpg" --alphaimg="watermark_alpha.jpg" IMG_20181202_18184044_2x1.jpg

GPS

Some H4V and 'Pro Mode' images do not have GPS co-ordinates stored (depending on your version of the RED Camera software). But with H4VAPP you can store the GPS co-ordinates from a 2D photo and then store them into your H4V photos:

~/h4vappcmd --savegps="Flying Fox" IMG_20181208_153741.jpg

Now use that location and apply it to an H4V conversion:

~/h4vappcmd --usegps="Flying Fox" IMG_20181202_18184044_2x1.jpg

Combining functions

Of course you'll want to put a watermark and EXIF data in one image, so you put the parameters together:

e.g.: creating an 'Pro Mode' image from H4V:

~/h4vappcmd --copyright --artist --txtwatermk --usegps="Home" IMG4044.jpg

Bulk changes and wildcards

You can use standard MacOS wildcards with the application.

For example: you can operate easily on all the 'Pro Mode' files in a given directory:

~/h4vappcmd --copyright --artist --txtwatermk --usegps="Home" IMG_*_2x1.jpg

You can also use the MacOS 'find' function to operate on all the 'Pro Mode' files in a given directory or any sub-directory:

find ~/Pictures -name "IMG_*_2x1.jpg" -exec ~/h4vappcmd \
--copyright --artist --txtwatermk --usegps="Home" {} \;

System Requirements

This edition is written for Mac OS X 10.10 and later. It was built using 10.12 (Sierra) and tested with (and the video shot on) 10.13 (High Sierra). It should work on 10.14 (Mojave) and 10.15 (macOS Catalina), but we're unable to test that right now. However, users have mentioned that it works on both without issue. The October 2022 release has been tested on macOS 11.7 (Big Sur). We have not tested Monterey or Ventura but will aim to do so later in 2023.

The Hydrogen used to test and create the supplied images with (and the video includes shots of) is:

2018

System Software: H1A1000.018ho.01.01.01r.144

Camera: 2.11.13

RED Player: V0.12.11

2020

System Software: H1A1000.018ho.01.01.01r.286

Camera: 3.9.10

Leia Player: v2.5