openPMD-CCD

This project is a python module for organizing CCD images with openPMD.

openPMD is an open meta-data schema that provides meaning and self-description to data sets in science and engineering. See the openPMD standard for details of this schema.

Install

# optional:            --user
python3 -m pip install        git+https://github.com/openPMD/openPMD-CCD.git

Usage (Write)

Python

Generally, you can use this as follows:

from openpmd_ccd import CCD
import numpy as np

scan = CCD("defaultCam_scan001.h5", overwrite=True,
           name="Go Pro", model="HERO8 Black", serial="12345678",
           operator="Axel Huebl <axelhuebl@lbl.gov>",
           # resolution=None, roi=None, exposure_time=None
)

# just a test: read from a file
scan.add(0, "tests/data/Scan005_SimCam_001.png")
# args: (image_number, image_data or image_path)

# this is faster and in-memory: data as a Python array
scan.add(1, np.array([[1., 2.], [3., 4.]]))

# scan.recalibrate(...)

scan.close()

LabView

For using this with LabView (2020 or newer), create a openpmd_ccd_labview.py wrapper file and populate it with the following content (link).

You have to name your CCDs uniquely.

You can now call the open_write, add, recalibrate and close functions with their respective parameters.

General latency estimate when starting python scripts from LabView (measured on a regular Windows PC in 2020):

• Session startup: ~250ms
• First function call into a module: ~1-2ms (simple numpy and h5py load)
• Further function calls: ~0.3ms

There are three modes to pass an image, exemplified with a 2250x2250 pixel image matrix (16bit depth):

• as numpy array (image_data as numpy.ndarray):
  • passing to Python: ~20-23ms
• as a list (image_data as list):
  • passing to Python: ~300ms (implicit list conversion)
  • converting list back to numpy: ~700ms
• via a file path (image_path as string):
  • overall: 100s of ms and more

The write of the actual data to HDF5 (add() call) in the given example takes about 9.1ms per image. All above values will change depending on Python installation, loaded modules and computer hardware (mainly memory and CPU).

Please see the example.vi file:

Usage (Read)

You can use any openPMD project for data processing with the created HDF5 files.

The openPMD-api project ships a full Python read interface and a little command-line tool called openpmd-ls to get a quick overview of a file:

openpmd-ls defaultCam_scan001.h5

The Python project openPMD-viewer can load the data like this:

from openpmd_viewer import OpenPMDTimeSeries

ts = OpenPMDTimeSeries('./defaultCam_scan001.h5')

# plot a single image in scan001
Ex, info_Ex = ts.get_field( iteration=0, field='raw', plot=True )

# use the Jupyter GUI
ts.slider()

As linked above, there are many more analysis options and programs that can read openPMD files: visualization tools, Python APIs, C++ APIs, and more.

Author Contributions

• Axel Huebl (LBNL): implementation
• Anthony Gonsalves (LBNL): consulting and LabView integration

License Note

Copyright (c) 2020, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.

If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov.

This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit others to do so.

TL;DR

The license is a BSD license with an added paragraph at the end that makes it easy for us to accept improvements without a hassle.

Transitive Contributions

• HDF5 by the HDF group and community
• the openPMD-standard by Axel Huebl (HZDR, now LBNL) and contributors