JPK Modules

For decoding and loading .jpk AFM file format into Python Numpy arrays.

load_jpk(file_path, channel, config_path=None, flip_image=True)

Load image from JPK Instruments .jpk files.

Parameters:

Name	Type	Description	Default
file_path	Path | str	Path to the .jpk file.	required
channel	str	The channel to extract from the .jpk file.	required
config_path	Path | str | None	Path to a configuration file. If ''None'' (default) then the packages default configuration is loaded from ''default_config.yaml''.	None
flip_image	bool	Whether to flip the image vertically. Default is True.	True

Returns:

Type	Description
tuple[NDArray, float]	A tuple containing the image and its pixel to nanometre scaling value.

Raises:

Type	Description
FileNotFoundError	If the file is not found.
KeyError	If the channel is not found in the file.

Examples:

Load height trace channel from the .jpk file. 'height_trace' is the default channel name.

>>> from AFMReader.jpk import load_jpk
>>> image, pixel_to_nanometre_scaling_factor = load_jpk(file_path="./my_jpk_file.jpk",
>>>                                                     channel="height_trace",
>>>                                                     flip_image=True)

Source code in AFMReader/jpk.py

def load_jpk(
    file_path: Path | str, channel: str, config_path: Path | str | None = None, flip_image: bool | None = True
) -> tuple[np.ndarray, float]:
    """
    Load image from JPK Instruments .jpk files.

    Parameters
    ----------
    file_path : Path | str
        Path to the .jpk file.
    channel : str
        The channel to extract from the .jpk file.
    config_path : Path | str | None
        Path to a configuration file. If ''None'' (default) then the packages default configuration is loaded from
        ''default_config.yaml''.
    flip_image : bool, optional
        Whether to flip the image vertically. Default is ``True``.

    Returns
    -------
    tuple[npt.NDArray, float]
        A tuple containing the image and its pixel to nanometre scaling value.

    Raises
    ------
    FileNotFoundError
        If the file is not found.
    KeyError
        If the channel is not found in the file.

    Examples
    --------
    Load height trace channel from the .jpk file. 'height_trace' is the default channel name.

    >>> from AFMReader.jpk import load_jpk
    >>> image, pixel_to_nanometre_scaling_factor = load_jpk(file_path="./my_jpk_file.jpk",
    >>>                                                     channel="height_trace",
    >>>                                                     flip_image=True)
    """
    logger.info(f"Loading image from : {file_path}")
    file_path = Path(file_path)
    filename = file_path.stem
    jpk_tags = _load_jpk_tags(config_path)
    try:
        tif = tifffile.TiffFile(file_path)
    except FileNotFoundError:
        logger.error(f"[{filename}] File not found : {file_path}")
        raise
    # Obtain channel list for all channels in file
    channel_list = {}
    for i, page in enumerate(tif.pages[1:]):  # [0] is thumbnail
        available_channel = page.tags[jpk_tags["channel_name"]].value  # keys are hexadecimal values
        if page.tags[jpk_tags["trace_retrace"]].value == 0:  # whether img is trace or retrace
            tr_rt = "trace"
        else:
            tr_rt = "retrace"
        channel_list[f"{available_channel}_{tr_rt}"] = i + 1
    try:
        channel_idx = channel_list[channel]
    except KeyError as e:
        logger.error(f"'{channel}' not in {file_path.suffix} channel list: {channel_list}")
        raise ValueError(f"'{channel}' not in {file_path.suffix} channel list: {channel_list}") from e

    # Get image and if applicable, scale it
    channel_page = tif.pages[channel_idx]
    image = channel_page.asarray()
    scaling, offset = _get_z_scaling(tif, channel_idx, jpk_tags)
    image = (image * scaling) + offset
    if flip_image is True:
        image = np.flipud(image)

    if channel_page.tags[jpk_tags["channel_name"]].value in ("height", "measuredHeight", "amplitude"):
        image = image * 1e9

    # Get page for common metadata between scans
    metadata_page = tif.pages[0]

    logger.info(f"[{filename}] : Extracted image.")
    return (image, _jpk_pixel_to_nm_scaling(metadata_page, jpk_tags))