openNCEM

https://openncem.readthedocs.io/en/latest/
Admin
A collection of packages and tools for electron microscopy data analysis supported by the National...
Tokens:135,860
Snippets:722
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install openNCEM

Source: https://openncem.readthedocs.io/en/latest/index.html

Install the ncempy package from PyPi. Use this command for basic installation.

```bash
>> pip install ncempy

```

--------------------------------

### Install ncempy package

Source: https://openncem.readthedocs.io/en/latest/_sources/index.rst.txt

Install the ncempy package from PyPi using pip.

```bash
>> pip install ncempy
```

--------------------------------

### Example Usage of line_profile

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/eval/line_profile.html

Demonstrates how to use the line_profile function with a sample image and prints the resulting profile.

```python
if __name__ == '__main__':

    XX, YY = np.mgrid[0:100,0:100]
    RR = np.sqrt((XX-50)**2 + (YY-50)**2)

    profile, (xx, yy) = line_profile(RR, (0,0), (99, 99), 100)
    print(profile)

```

--------------------------------

### Dummy Settings Dictionary

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/eval/ring_diff.html

A sample dictionary representing all possible settings for ring diffraction analysis, with all parameters set to example values.

```python
dummy_settings = {'lmax_r': 1,
                    'lmax_thresh': 1,
                    'lmax_cinit': (1,1),
                    'lmax_range': (1.,2.),
                    'plt_imgminmax': (0.0,1.0),
                    'ns': (1,),
                    'rad_rmax': 1,
                    'rad_dr': 0.1,
                    'rad_sigma': 0.1,
                    'mask': np.ones((5,5)),
                    'fit_rrange': (1.0, 2.0),
                  'back_xs': (1.0, 2.0, 3.0),
                  'back_xswidth': 0.1,
                  'back_init': (1.0, 1.0, 1.0),
                  'fit_funcs': ('voigt',),
                  'fit_init': (1.0, 1.0, 1.0, 1.0),
                  'fit_maxfev':10
                  }
```

--------------------------------

### Install ncempy with EDSTomo module

Source: https://openncem.readthedocs.io/en/latest/_sources/index.rst.txt

Install the ncempy package with the optional EDSTomo module.

```bash
pip install 'ncempy[edstomo]'
```

--------------------------------

### Install openNCEM with EDSTomo module

Source: https://openncem.readthedocs.io/en/latest/index.html

Install the ncempy package with the optional EDSTomo module. This command includes additional dependencies for EDSTomo functionality.

```bash
pip install 'ncempy[edstomo]'

```

--------------------------------

### Get Fluorescence Line Energy Examples

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/edstomo/CharacteristicEmission.html

Demonstrates how to retrieve fluorescence line energies for different elements, series, and lines using the GetFluorescenceLineEnergy function. This is useful for accessing atomic data required for X-ray spectroscopy.

```python
if __name__ == '__main__':
    print('------------------------------')
    # print('Fe-K: %s' % GetFluorescenceLineEnergy('Fe'))
    # print('Al-K: %s' % GetFluorescenceLineEnergy('Al'))
    # print('Mg-K: %s' % GetFluorescenceLineEnergy('Mg'))
    # print('Mg-K: %s' % GetFluorescenceLineEnergy('Mg', Series='K'))
    # print('Mg-K: %s' % GetFluorescenceLineEnergy('Mg', Series='K', Line='K'))
    # print('Fe-Q: %s' % GetFluorescenceLineEnergy('Fe', Series='Q'))
    # print('Fe-Ka2: %f' % GetFluorescenceLineEnergy('Fe', Series='K', Line='Ka2'))
    # print('Fe-Ka1: %f' % GetFluorescenceLineEnergy('Fe', Series='K', Line='Ka1'))
    # print('Fe-Ka: %f' % GetFluorescenceLineEnergy('Fe', Series='K', Line='Ka'))
    # print('Fe-Kb: %f' % GetFluorescenceLineEnergy('Fe', Series='K', Line='Kb'))
    # print('Mn-Ka: %f' % GetFluorescenceLineEnergy('Mn', Series='K', Line='Ka'))
    # print('Pt-La: %f' % GetFluorescenceLineEnergy('Pt', Series='L', Line='La'))
    print('S-K: %f' % GetFluorescenceLineEnergy('S', Series='K', Line='K'))
```

--------------------------------

### Example Usage of line_profile

Source: https://openncem.readthedocs.io/en/latest/ncempy.eval.html

Demonstrates how to use the line_profile function to extract a line scan from an image and visualize the results. Requires matplotlib for plotting.

```python
import matplotlib.pyplot as plt

# Assuming 'image' is a pre-defined 2D numpy array
# line, (xx, yy) = line_profile(image,(0,100),(175,100),50,step=0.5,width=5)
# fg, ax = plt.subplots(1,2)
# ax[0].plot(line,'*-')
# ax[1].imshow(image)
# ax[1].scatter(xx, yy)
```

--------------------------------

### Open and Inspect Velox EMD File with fileEMDVelox

Source: https://openncem.readthedocs.io/en/latest/ncempy.io.html

This example demonstrates how to open a Velox EMD file using the fileEMDVelox class. It shows how to print file information and retrieve a specific dataset and its metadata.

```python
import ncempy.io as nio

# Open an EMD Velox file containing 1 image
with nio.emdVelox.fileEMDVelox('1435 1.2 Mx STEM HAADF-DF4-DF2-BF.emd') as emd1:
    # print information about the file
    print(emd1)
    # Retrieve the first dataset (index 0) and its metadata
    im0, metadata0 = emd1.get_dataset(0)
```

--------------------------------

### Read Full Multi-Image DM3 File into Memory

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/dm.html

This example shows how to load an entire multi-image DM3 file into memory using the fileDM class. This is useful for processing series of images.

```python
with dm.fileDM('imageSeries.dm3')as dmFile2:
    series = dmFile2.getDataset(0)
```

--------------------------------

### Low-level MRC file access with fileMRC

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/mrc.html

For advanced users and developers, the fileMRC class allows direct access to the MRC file's internals. This example demonstrates how to open a file and retrieve a single slice of the 3D data.

```python
import ncempy.io as nio
with nio.mrc.fileMRC('file.mrc') as f1:
    single_slice = f1.getSlice(0)
```

--------------------------------

### Minimum Dummy Settings Dictionary

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/eval/ring_diff.html

A sample dictionary representing ring diffraction settings where optional parameters are set to None, useful for testing default behavior or minimal configurations.

```python
min_dummy_settings = {'lmax_r': 1,
                        'lmax_thresh': 1,
                        'lmax_cinit': (1,1),
                        'lmax_range': (1.,2.),
                        'plt_imgminmax': None,
                        'ns': (1,),
                        'rad_rmax': None,
                        'rad_dr': None,
                        'rad_sigma': None,
                        'mask': None,
                        'fit_rrange': (1.0, 2.0),
                      'back_xs': (1.0, 2.0, 3.0),
                      'back_xswidth': 0.1,
                      'back_init': (1.0, 1.0, 1.0),
                      'fit_funcs': ('voigt',),
                      'fit_init': (1.0, 1.0, 1.0, 1.0),
                      'fit_maxfev': None
                      }
```

--------------------------------

### Initialize EMDVelox Reader

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/emdVelox.html

Import the ncempy.io module and initialize the EMDVeloxReader with a filename and dataset number. This is the primary way to open and prepare an EMD file for reading.

```python
import ncempy.io as nio


emd0 = nio.emdVelox.emdVeloxReader('filename.emd', dsetNum = 0)
```

--------------------------------

### Get Specific or Weighted Fluorescence Line Energy

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/edstomo/CharacteristicEmission.html

Retrieves the energy of a characteristic X-ray fluorescence line for a given element and series. It can return the energy of a specific line, a weighted sum for a subseries (like 'Ka' or 'Lb'), or the weighted sum for the entire series if no specific line is requested. Use this to get precise energy values for spectral analysis.

```python
[docs]def GetFluorescenceLineEnergy(ElementName, Series='K', Line=None):
    LineData = GetElamFluorescenceLines(ElementName)

    # If the user requests a "line" which is the series, we will return the weighted sum of all lines in the series (below in the if).
    if Line == Series:
        Line = None

    # If the user specifies a specific line, then we will return its energy.
    try:
        if Line in ['Ka', 'Kb', 'La', 'Lb']:
            # We can make weighted sums of special subseries of lines. 
            return GetWeightedSum(Line, LineData[Series])
        elif Line is not None:
            # Or we can return a specific line which is requested.
            # print(LineData)
            return LineData[Series][Line][0]
        else:
            # The user doesn't specify a line which means he wants to know the energy of the whole series.
            return GetWeightedSum(Series, LineData[Series])
    except:
        
```

--------------------------------

### Get Dataset from EMDVelox

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/emdVelox.html

Retrieves data from a specified group within an EMD file. Supports returning data as a numpy array or as a memory-mapped HDF5 dataset.

```python
def get_dataset(self, group, memmap=False):
        """ Get the data from a group and the associated metadata.

        Parameters
        ----------
            group : HDF5 dataset or int
                The link to the HDF5 dataset in the file or an integer for the
                number of the dataset. The list of datasets is held in the
                list_data attribute populated on class init.
            memmap: bool, default = False
                If False (default), then a numpy ndarray is returned. If True
                the HDF5 data set object is returned and data is loaded from
                disk as needed.

        Returns
        -------
            : tuple (ndarray or HDF5 dataset, dict)
                A tuple containing the data as a ndarray or a HDF5 dataset object.
                The second argument is a python dict of metadata.
        """
        # check input
        try:
            if isinstance(group, int):
                group = self.list_data[group]
        except IndexError:
            raise IndexError('EMDVelox group #{} does not exist.'.format(group))
        
        if not isinstance(group, h5py.Group):
            raise TypeError('group needs to refer to a valid HDF5 group!')

        if memmap:
            data = group['Data']  # return the HDF5 dataset object
        else:
            data = np.squeeze(group['Data'][:])  # load the full data set
        metaData = self.parseMetaData(group)
        return data, metaData
```

--------------------------------

### Create and Configure EMD File

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/edstomo/bruker.html

Sets microscope attributes and adds a comment to an EMD file before closing it. Ensure all necessary variables like BeamEnergy, EnergyResolutionMnKa, DetectorTiltAngle, RealTime, Tilts, and OutputEMD are defined.

```python
EMD.microscope.attrs['BeamVoltage[eV]'] = BeamEnergy
EMD.microscope.attrs['MnKaResolution[eV]'] = EnergyResolutionMnKa
EMD.microscope.attrs['DetectorTiltAngle[deg]'] = DetectorTiltAngle
EMD.microscope.attrs['RealTime[s]'] = RealTime * len(Tilts)

EMD.put_comment('File created.')
del EMD
print('Created file ' + OutputEMD)
```

--------------------------------

### Get EMD Data from Group

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/emd.html

Retrieves the EMD data stored within a specified HDF5 group. Note that the 'memmap' keyword has been removed and 'get_memmap()' should be used instead.

```python
def get_emdgroup(self, group):
    """Get the emd data saved in the requested group.

    Note
    ____
    The memmap keyword has been removed. Please use get_memmap().

    Parameters
    ----------
        group: h5py._hl.group.Group or int
            Reference to the HDF5 group to load. If int is used then the item corresponding to self.list_emds

```

--------------------------------

### Initialize Elam Database Loading Flags

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/edstomo/CharacteristicEmission.html

Sets flags to manage the loading of the Elam database, ensuring it's loaded only once. Includes a lambda function for optional debugging output.

```python
from io import StringIO
import numpy as np
import pickle
import itertools
import os, sys, shutil

ElamLoaded = False # We only want to load the Elam database once.  Keep track of if that has been done.  False = not yet loaded.
ElamData = []

# For debugging we sometimes want Elam to print out the lines it loaded.
ElamPrint = lambda s: None #print(s)

# Reading the Elam database is time consuming.  This caches the fluorescence data so it is only read once per program
```

--------------------------------

### Get Dataset and Metadata from EMD File

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/emdVelox.html

Accesses a dataset and its associated metadata from an EMD file using the emdVeloxReader. It returns a dictionary containing the data, filename, and metadata.

```python
with fileEMDVelox(filename) as emd0:
    d, md = emd0.get_dataset(dsetNum)
    out = {'data': d, 'filename': filename}
    out.update(md)

    return out
```

--------------------------------

### Read MRC File and Header

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/mrc.html

Reads an MRC file, parses its header, and returns the full dataset along with metadata. Assumes a 3-dimensional dataset for plotting examples.

```python
from ncempy.io.mrc import mrcReader
import matplotlib.pyplot as plt
mrc1 = mrcReader('filename.mrc')
plt.imshow(mrc1['data'][0, :, :])  # show the first image in the data set
```

--------------------------------

### Import ncempy and standard libraries

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/eval/ring_diff.html

Imports algorithms for local maxima, distortion, radial profiles, math, and EMD I/O, along with numpy and h5py for numerical operations and data handling.

```python
import ncempy.algo.local_max
import ncempy.algo.distortion
import ncempy.algo.radial_profile
import ncempy.algo.math
import ncempy.io.emd

#import matplotlib.pyplot as plt
import numpy as np
import h5py
```

--------------------------------

### Reading a Dataset with fileDM

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/dm.html

Demonstrates how to open a DM file using fileDM and retrieve a specific dataset. This function is useful for loading data directly into memory and obtaining spatial axes.

```python
from ncempy.io import dm
import matplotlib.pyplot as plt

im0 = dm.dmReader('filename.dm3')
plt.imshow(im0['data'])
```

--------------------------------

### Get Encoded Type Size in Bytes

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/dm.html

Returns the number of bytes for a given DM encoded data type. Handles common types and returns -1 for unlisted types.

```python
    def _encodedTypeSize(self, encodedType):
        """Return the number of bytes in a data type for the encodings used by DM.
        Constants for the different encoded data types used in DM files as as follows:
            SHORT   = 2
            LONG    = 3
            USHORT  = 4
            ULONG   = 5
            FLOAT   = 6
            DOUBLE  = 7
            BOOLEAN = 8
            CHAR    = 9
            OCTET   = 10
            uint64  = 12
            -1 will signal an unlisted type

        Parameters
        ----------
            encodedType : int
                The type value read from the header.

        Returns
        -------
            encodedTypeSize : int
                Number of bytes this type uses.
        """
        try:
            return self._encodedTypeSizes[encodedType]
        except KeyError:
            return -1
        except:
            raise
```

--------------------------------

### ncempy.eval.ring_diff.run_all

Source: https://openncem.readthedocs.io/en/latest/ncempy.eval.html

Runs all evaluations on a set-up EMD file and saves the results.

```APIDOC
## ncempy.eval.ring_diff.run_all

### Description
Run on a set-up emd file to do evaluations and save results.
All evaluations within parent are run.

### Parameters
* **parent** (_h5py.Group_) – Handle to parent.
* **outfile** (_ncempy.io.emd.fileEMD_) – Emdfile for output.
* **overwrite** (_bool_) – Set to overwrite existing results in outfile.
* **verbose** (_bool_) – Set to get verbose output during run.
* **showplots** (_bool_) – Set to directly show plots interactively.

### Returns
None
```

--------------------------------

### Get Numpy Memmap for MRC Data

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/mrc.html

Returns a read-only numpy memmap object for accessing large MRC datasets without loading them entirely into memory. Useful for memory-constrained environments.

```python
mm = np.memmap(self.fid, dtype=self.dataType, mode='r', offset=self.dataOffset,
                       shape=tuple(self.dataSize))

        return mm
```

--------------------------------

### defaultDims

Source: https://openncem.readthedocs.io/en/latest/ncempy.io.html

A helper function that can generate a properly setup dim tuple with default values to allow quick writing of EMD files without the need to create these dim vectors manually.

```APIDOC
## defaultDims(data, pixel_size=None)

### Description
A helper function that can generate a properly setup dim tuple with default values to allow quick writing of EMD files without the need to create these dim vectors manually.

### Parameters
* **data** (ndarray) - The data that will be written to the EMD file. This is used to get the number of dims and their shape.
* **pixel_size** (tuple, optional) - A tuple of pixel sizes. Must have the same length as the number of dimensions of data.

### Returns
A properly formatted tuple of dim vectors used as input to emd.emdFile.put_emdgroup().

### Return Type
list
```

--------------------------------

### run_singleImage

Source: https://openncem.readthedocs.io/en/latest/ncempy.algo.html

Evaluate a single ring diffraction pattern with given settings.

```APIDOC
## run_singleImage

### Description
Evaluate a single ring diffraction pattern with given settings.

### Parameters
#### Positional Parameters
* **img** (np.ndarray) - Image.
* **dims** (tuple) - Dimensions tuple.
* **settings** (dict) - Dictionary containing settings for evaluation. See module documentation for details on expected keys.
#### Optional Parameters
* **show** (bool) - If True, display the results. Defaults to False.

### Returns
(Not specified in source)

### Return Type
(Not specified in source)
```

--------------------------------

### Create Volume from Gaussian Peaks

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/algo/peak_find.html

Generates a 3D volume by placing Gaussian peaks at specified positions. Requires peak list, volume shape, and Gaussian parameters.

```python
def peaksToVolume(peakList, volShape, gaussSigma, gaussSize, indexing='ij'):
    """ Place 3D Gaussian at a set of peak positions.
    
    Parameters
    ----------
        peakList : np.ndarray
            Array of peak positions of size (numPeaks, 3).
        
        volShape : tuple
            3 element tuple of the shape of the volume containing the peaks
        
        gaussSigma : tuple
            3 element tuple with that sigma parameters passed to the gaussND.gauss3D() function (sigX,sigY,sigZ)
        
        gaussSize : tuple
            3 element tuple describing the 3D size of the simulated gaussian box. Must be odd.

        indexing : str
            String to pass to np.meshgrid to indicate which indexing is used. Either 'ij' or 'xy' are possible. Default
            is 'ij' for this module.
    Returns
    -------
        : np.ndarray
            A volume containing gaussian peaks at each position indicated in peakList parameter.
    
    """

    sim_volume = np.zeros(volShape, dtype=np.float32)

    if np.any(np.array(gaussSize) % 2 == 0):
        raise ValueError('gaussSize must be odd.')

    sz = [int((g - 1) // 2) for g in gaussSize]
    temp0 = np.arange(-sz[0], sz[0]+1)
    temp1 = np.arange(-sz[1], sz[1]+1)
    temp2 = np.arange(-sz[2], sz[2]+1)
    Y3D, X3D, Z3D = np.meshgrid(temp0, temp1, temp2, indexing=indexing)

    for pos in peakList:
        pos_loc = (pos // 1).astype(int)

        pos_remain = pos % 1
        gg3 = gaussND.gauss3D(Y3D, X3D, Z3D,
                              pos_remain[0], pos_remain[1], pos_remain[2],
                              gaussSigma[0], gaussSigma[1], gaussSigma[2])

        sim_volume[pos_loc[0] - sz[0]:pos_loc[0] + sz[0] + 1,
                   pos_loc[1] - sz[1]:pos_loc[1] + sz[1] + 1,
                   pos_loc[2] - sz[2]:pos_loc[2] + sz[2] + 1] += gg3
    return sim_volume
```

--------------------------------

### Get EMD Dimensions from Group

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/emd.html

Retrieves the dimensional information (vectors, names, and units) for the 'data' dataset within a specified EMD HDF5 group. Handles potential byte decoding for names and units.

```python
def get_emddims(self, group):
    """Get the emdtype dimensions saved in in group.

    Parameters
    ----------
        group: h5py.Group
            Reference to the emdtype HDF5 group.

    Returns
    -------
        : tuple
            List of dimension vectors plus labels and units.

    """
    # get the dims
    dims = []
    for ii in range(group['data'].ndim):
        dim = group['dim{}'.format(ii + 1)]
        # save them as (vector, name, units)

        if 'name' in dim.attrs:
            if isinstance(dim.attrs['name'], np.ndarray):
                name = dim.attrs['name'][0]
            else:
                name = dim.attrs['name']
        else:
            name = 'dim{}'.format(ii + 1)

        if 'units' in dim.attrs:
            if isinstance(dim.attrs['units'], np.ndarray):
                units = dim.attrs['units'][0]
            else:
                units = dim.attrs['units']
        else:
            units = 'pixels'

        # Handle bytes objects by decoding them to strings
        # If something goes wrong, the original attribute is left as-is
        try:
            if isinstance(name, bytes):
                name = name.decode('utf-8')
            if isinstance(units, bytes):
                units = units.decode('utf-8')
        except:
            pass

        dims.append((dim[:], name, units))

    dims = tuple(dims)
    return dims
```

--------------------------------

### Read SER file data using fileSER

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/ser.html

Demonstrates how to open a SER file and retrieve a specific dataset (e.g., an image) using the low-level API. This is useful for accessing individual images within a series.

```python
import matplotlib.pyplot as plt
import ncempy.io as nio
with nio.ser.fileSER('filename.ser') as ser1:
   data, metadata = ser1.getDataset(0)
```

--------------------------------

### Create and Write SER Dimensions

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/ser.html

This snippet demonstrates how to create dimension datasets from SER file headers and write them to a file group. It handles the first dimension as a number and subsequent dimensions based on metadata, including calibration information and units.

```python
                # create dimension datasets
                dims = []

                # first SER dimension is number
                assert self.head['Dimensions'][0]['Description'] == 'Number'
                dim = self._createDim(self.head['Dimensions'][0]['DimensionSize'],
                                      self.head['Dimensions'][0]['CalibrationOffset'],
                                      self.head['Dimensions'][0]['CalibrationDelta'],
                                      self.head['Dimensions'][0]['CalibrationElement'])
                dims.append((dim[0:self.head['ValidNumberElements']], self.head['Dimensions'][0]['Description'],
                             '[{}]'.format(self.head['Dimensions'][0]['Units'])))

                dim = self._createDim(first_meta['ArrayShape'][0], first_meta['Calibration'][0]['CalibrationOffset'],
                                      first_meta['Calibration'][0]['CalibrationDelta'],
                                      first_meta['Calibration'][0]['CalibrationElement'])
                dims.append((dim, 'E', '[m_eV]'))

                # write dimensions
                for i in range(len(dims)):
                    f.write_dim('dim{:d}'.format(i + 1), dims[i], grp)

                # write out time as additional dim vector
                f.write_dim('dim1_time', (time, 'timestamp', '[s]'), grp)
```

--------------------------------

### Get Metadata from DM File

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/dm.html

Retrieves useful metadata from a DM file, excluding thumbnails and parsing specific sections like 'Calibrations', 'Acquisition', 'EELS', etc. Handles 'Tecnai Microscope Info' separately.

```python
    def getMetadata(self, index):
        """ Get the useful metadata in the file. This parses the allTags dictionary and retrieves only the useful
        information about hte experimental parameters. This is a (useful) subset of the information contains in the
        allTags attribute.

        Note: some DM files contain extra information called the Tecnai Microscope Info. This is added to the metadata
        dictionary as a string.


        Parameters
        ----------
        index : int
            The number of the dataset to get the metadata from.
        """

        # The first dataset is usually a thumbnail. Test for this and skip the thumbnail automatically
        # metadata indexing starts at 1 but the index keyword starts at 0
        if self.numObjects == 1:
            index = 1  # the first data set will have a 1 in the metadata
        else:
            index += 2  # the thumbnail is index = 1. The actual data will needs to start at 2.

        # Check that the dataset exists.
        try:
            self._checkIndex(index)
        except:
            raise

        good_keys = ['Calibrations', 'Acquisition', 'DataBar', 'EELS', 'Meta Data', 'Microscope Info', ]

        # Determine useful meta data UNTESTED
        prefix1 = '.ImageList.{}.ImageTags.'.format(index)
        prefix2 = '.ImageList.{}.ImageData.'.format(index)
        for kk, ii in self.allTags.items():
            if prefix1 in kk or prefix2 in kk:
                kk_split = kk.split('.')
                if kk_split[4] in good_keys:
                    new_key = ' '.join(kk_split[4:])
                    self.metadata[new_key] = ii

            if 'Tecnai.Microscope Info.arrayOffset' in kk:
                try:
                    offset = self.allTags[prefix1 + 'Tecnai.Microscope Info.arrayOffset']
                    size = self.allTags[prefix1 + 'Tecnai.Microscope Info.arraySize']
                    dtype = self.allTags[prefix1 + 'Tecnai.Microscope Info.arrayType']
                    cur_offset = self.fid.tell()
                    self.seek(self.fid, offset)
                    string_data = self.fromfile(self.fid, count=size, dtype=np.uint16)
                    tecnai = ''.join([chr(ii) for ii in string_data]).replace('\u2028', ';')  # replace new line with ;
                    self.metadata['Tecnai Microscope Info'] = tecnai
                except KeyError:
                    print('Tecnai parse error')

        return self.metadata
```

--------------------------------

### Get Ring Diffraction Settings from HDF5

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/eval/ring_diff.html

Reads radial profile evaluation settings from an HDF5 group. It validates the group type and settings version, then extracts various parameters, handling optional parameters by setting them to None if not found.

```python
def get_settings( parent ):
    """Get settings for radial profile evaluation.

    Parameters
    ----------
        parent : h5py.Group
            Input group.

    Returns
    -------
        : dict
            Settings read from parent.

    """
    
    try:
        assert(isinstance(parent, h5py._hl.group.Group))
    except:
        raise TypeError('Something wrong with the input.')

    if not parent.attrs['type'] == np.string_(cur_set_vers):
        print('Don\'t  know the format of these settings.')
        return None
    
    settings = {}
    
    settings['lmax_r'] = parent.attrs['lmax_r']
    settings['lmax_thresh'] = parent.attrs['lmax_thresh']
    settings['lmax_cinit'] = parent.attrs['lmax_cinit']
    settings['lmax_range'] = parent.attrs['lmax_range']
    settings['ns'] = parent.attrs['ns']
    settings['fit_rrange'] = parent.attrs['fit_rrange']
    settings['back_xs'] = parent.attrs['back_xs']
    settings['back_xswidth'] = parent.attrs['back_xswidth']
    settings['back_init'] = parent.attrs['back_init']
    settings['fit_init'] = parent.attrs['fit_init']

    if isinstance(parent.attrs['fit_funcs'], np.ndarray):
        in_funcs = parent.attrs['fit_funcs'][0]
    else:
        in_funcs = parent.attrs['fit_funcs']
    in_funcs = in_funcs.split(b',')
        
    out_funcs = []
    for i in range(len(in_funcs)):
        out_funcs.append(in_funcs[i].decode('utf-8').strip())
    settings['fit_funcs'] = tuple(out_funcs)

    if 'plt_imgminmax' in parent.attrs:
        settings['plt_imgminmax'] = parent.attrs['plt_imgminmax']
    else:
        settings['plt_imgminmax'] = None

    if 'rad_rmax' in parent.attrs:
        settings['rad_rmax'] = parent.attrs['rad_rmax']
    else:
        settings['rad_rmax'] = None

    if 'rad_dr' in parent.attrs:
        settings['rad_dr'] = parent.attrs['rad_dr']
    else:
        settings['rad_dr'] = None

    if 'rad_sigma' in parent.attrs:
        settings['rad_sigma'] = parent.attrs['rad_sigma']
    else:
        settings['rad_sigma'] = None

    if 'mask' in parent:
        settings['mask'] = np.copy(parent['mask'])
    else:
        settings['mask'] = None

    if 'fit_maxfev' in parent.attrs:
        settings['fit_maxfev'] = parent.attrs['fit_maxfev']
    else:
        settings['fit_maxfev'] = None

    return settings
```

--------------------------------

### Load Single Image Data with serReader

Source: https://openncem.readthedocs.io/en/latest/ncempy.io.html

Utilize the simplified serReader function to load all data and metadata from a SER file into a dictionary. This is the recommended approach for general users.

```python
import ncempy.io as nio
ser1 = nio.ser.serReader(‘filename_1.ser’)
plt.imshow(ser1[‘data’]) # show the single image from the data file
```

--------------------------------

### tell()

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/io/dm.html

Returns the current position in the file. It adapts its behavior based on the 'on_memory' mode.

```APIDOC
## tell()

### Description
Returns the current position in the file. Switches mode based on on_memory mode.

### Returns
- **pos** (int) - The current position in the file.

```

--------------------------------

### Low-level MRC file operations with fileMRC

Source: https://openncem.readthedocs.io/en/latest/ncempy.io.html

Access file internals using the mrc.fileMRC() class for advanced operations. This example shows how to read a single slice from a large MRC file without loading the entire dataset into memory.

```python
import ncempy.io as nio
with nio.mrc.fileMRC(‘file.mrc’) as f1:
    single_slice = f1.getSlice(0)
```

--------------------------------

### Display Image and FFT Side-by-Side

Source: https://openncem.readthedocs.io/en/latest/ncempy.viz.html

Shows an image and its FFT next to each other. If the FFT is not provided, it is calculated using np.fft.fft2. The pixel spacing can be specified.

```python
import ncempy.viz
import numpy as np

# Assuming 'im' is a numpy array representing the image
# and 'd' is the pixel spacing
# ncempy.viz.im_and_fft(im, d=pixel_spacing)
```

--------------------------------

### Get Bruker Tilt Angles from Filenames

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/edstomo/bruker.html

Extracts tilt angles from Bruker '.bcf' filenames in a specified directory. Assumes filenames are formatted like '...-10.bcf', '-5.bcf', '0.bcf', etc. The function sorts the extracted angles numerically.

```python
import sys, os, shutil
from collections import OrderedDict
import glob2 as glob
import numpy as np
import hyperspy.api as hs
from ncempy.io.emd import fileEMD


[docs]
def GetTiltsFromBrukerSequence(Directory=None):
    ''' Find the set of Bruker bcf files and figure out their tilts based on filenames.

    There should be a set of bcf files in a directory with names: ... -10.bcf, -5.bcf, 0.bcf, 5.bcf ...
    The number represents the stage tilt of that stack.
    The angles do not matter but the names must be coded as above.  They will be automatically read and sorted.

    Parameters:
        Directory (str): Name of directory containing the bcf files.

    Returns:
        (list of floats): A list of tilt angles.
    '''

    Bcfs = glob.glob(os.path.join(Directory, '*.bcf'))
    NewBcfs = []
    for i in Bcfs:
        _ , FileName = os.path.split(i)
        NewBcfs.append(FileName)
    Tilts = list(map(lambda s: float(s[:-4]), NewBcfs))
    Tilts.sort()

    return Tilts

```

--------------------------------

### Fit Radial Profile Convenience Wrapper

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/algo/radial_profile.html

A wrapper function for fitting radial profiles using `scipy.optimize.leastsq`. It handles input validation and parameter reshaping.

```python
import numpy as np
import scipy.optimize
import ncempy.algo.math

def fit_radialprofile(r, intens, funcs, init_guess, maxfev=None):
    """Fit the radial profile.

    Convenience wrapper for fitting.

    Parameters
    -----------
        r : np.ndarray
            r-axis of radial profile.
        intens : np.ndarray
            Intensity-axis of radial profile.
        funcs : tuple
            List of functions.
        init_guess : np.ndarray
            Initial guess for parameters of functions in funcs.
        maxfev : int
           maximum function calls (for scipy.optimize.leastsq)

    Returns
    --------
        : np.ndarray
            Optimized parameters.

    """

    try:
        # check data
        assert (isinstance(r, np.ndarray))
        assert (isinstance(intens, np.ndarray))
        assert (np.array_equal(r.shape, intens.shape))

        # funcs and params
        assert (len(funcs) >= 1)
        for i in range(len(funcs)):
            assert (funcs[i] in ncempy.algo.math.lkp_funcs)

        init_guess = np.array(init_guess)
        init_guess = np.reshape(init_guess, sum(map(lambda x: ncempy.algo.math.lkp_funcs[x][1], funcs)))

    except:
        raise TypeError('Something wrong with the input!')

    if maxfev is None:
        maxfev = 1000

    popt, flag = scipy.optimize.leastsq(residuals_fit, init_guess, args=(r, intens, funcs), maxfev=maxfev)

    if flag not in [1, 2, 3, 4]:
        print('WARNING: fitting of radial profile failed.')

    return popt

```

--------------------------------

### ncempy.command_line.ncem2png Script

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/command_line/ncem2png.html

The main script for converting SER, DM3, and DM4 files to PNG. It includes functions for discovering associated .emi files, extracting image dimensions, and handling the conversion process.

```python
""" This scripts converts SER, DM3, and DM4 files into PNG """

import argparse
from ncempy.io.dm import fileDM
from ncempy.io.ser import fileSER
import ntpath
import os

from matplotlib import cm
from matplotlib.image import imsave

def _discover_emi(file_route):
    file_name = ntpath.basename(file_route)
    folder = os.path.dirname(file_route)
    parts = file_name.split("_")
    if len(parts)==1:
        # No "_" in the filename.
        return None
    emi_file_name = "{}.emi".format("_”.join(parts[:-1])))
    emi_file_route = os.path.join(folder, emi_file_name)
    if not os.path.isfile(emi_file_route):
        # file does not exist
        return None
    
    return emi_file_route


[docs]
def extract_dimension(img, fixed_dimensions=None):
    out_img=img

    dimension=len(img.shape)
    if fixed_dimensions is None:
        if dimension == 3:
            fixed_dimensions=[int(img.shape[0]/2),
                              '','']
        elif dimension == 4:
            fixed_dimensions=['',
                              int(img.shape[2]/2),
                              int(img.shape[3]/2)]
        elif dimension > 4:
            raise ValueError("This scripts cannot extract PNGs from DM files"
                            " with"
                             
```

```python
                             
```

```python
"more than four dimensions without explicit"
                             " use of --fixed_dimensions.")

    if len(fixed_dimensions)!=dimension:
        raise ValueError("Number of values to index the image ({}) do not"
                         
```

```python
"match the image dimension ({}).".format(
                             len(fixed_dimensions), dimension))
    d_tuple=()
    selected_dimensions=0
    print("{}D Selecting frame ({})".format(dimension,
                                            fixed_dimensions))
    for (d, s) in zip(fixed_dimensions, img.shape):
        if not d:
            d_tuple+=(slice(None, None, None),)
        elif d=="m":
            d_tuple+=(int(s/2),)
            selected_dimensions+=1
        elif int(d)<s:
            selected_dimensions+=1
            d_tuple+=(int(d),)
    if dimension-selected_dimensions!=2:
        raise ValueError("Dimension extractor do not fix enough components"
                         
```

```python
"to produce a 2D image. Needs to fix: {}"
                         "{}".format(dimension-2))
    out_img = img[d_tuple] 
    return out_img


[docs]
def dm_to_png(source_file, dest_file, fixed_dimensions=None):
    """ Saves the DM3 or DM4 source_file as PNG dest_file. If the data has three
    of four dimensions. The image taken is from the middle image in those
    dimensions."""
    f = fileDM(source_file, on_memory=True)
    f.parseHeader()
    ds = f.getDataset(0)
    img = ds['data']
    img = extract_dimension(img, fixed_dimensions)
    imsave(dest_file, img, format="png", cmap=cm.gray)
    return f



[docs]
def ser_to_png(source_file, dest_file):
    """ Saves the SER source_file as PNG dest_file."""
    emi_file = _discover_emi(source_file)
    f = fileSER(source_file, emi_file)
    ds = f.getDataset(0)
    img = ds[0]
    imsave(dest_file, img, format="png")
    return f

    

[docs]
def main():
    parser = argparse.ArgumentParser(description='Extracts a preview png from'
                                     ' a SER, DM3, or DM4 file.')
    
    parser.add_argument('source_files', metavar='source_files', type=str,
                        nargs="+",
                    help='Source files, must have ser, dm3, o dm4 extension.')
    
    parser.add_argument('--out_file', dest='dest_file', action='store',
                        type=str, nargs=1,
                        help='Filename to write the preview png file. If not set'
                        ' it defaults to the name of the source file appending'
                        ' png. Only valid when a single input file is '
                        ' processed.',
                        default=None)
    
    parser.add_argument('--fixed_dimensions', dest='fixed_dimensions',
                        action='store',
                        type=str, nargs=1,
                        help="List of numbers, 'm'(for middle), or nothing to"
                        
```

```python
"extract"
                         
```

```python
"a particular slice of data. e.g., '2,,' will extract"
                         "an png with the values y,z of x=2. ',m,,2' will "
                         "extract all the values x,z for y=1/2shapeY, and w=2.",
                        default=None)
    
    args = parser.parse_args()
    
    
    if args.dest_file is not None and len(args.source_files)>1:
        raise ValueError("--out_file only can be used when a single input file"
                         
```

```python
"is processed.")
    
    fixed_dimensions = args.fixed_dimensions
    if fixed_dimensions is not None:
        fixed_dimensions=fixed_dimensions[0].split(',')
    
    for source_file in args.source_files:
        
        if args.dest_file is None:

```

--------------------------------

### Read Digital Micrograph file (developer access)

Source: https://openncem.readthedocs.io/en/latest/_sources/index.rst.txt

For developers needing full access to the internal file structure, instantiate the `fileDM` class. This allows access to all metadata and datasets within the file.

```python
>>> import ncempy.io as nio
>>> with nio.dm.fileDM('/path/to/file/data.dm3') as dm0:
>>>     dmData = dm0.getDataset(0) #the full first data set
>>>     dmSlice = dm0.getSlice(0, 1) #the second image of the first data set; equal to dmData[1,:,:] from the line above
>>>     print(dm0.metaData) # all of the interesting metadata for this data set (pixel size, accelerating voltage, etc.)
>>>     print(dm0.allTags) # all of the tags in the file including tags specific to the Digital Micrpograph software program
```

--------------------------------

### Interactive 3D Stack Viewer

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/viz.html

Creates an interactive viewer for a 3D image stack using a slider to navigate through slices. Requires matplotlib and its widgets.

```python
from matplotlib.widgets import Slider

class StackViewer:
    """
    Visualize a 3D stack of images with a slider.

    Parameters
    ----------
    stack : numpy.ndarray, 3D stack
        The stack of to show as images

    **kwargs :
        Passed directly to pyplot.imshow()

    """

    def __init__(self, stack, **kwargs):
        from matplotlib.widgets import Slider

        if stack.ndim != 3:
            raise Exception('Must be three-dimensional stack of images.')

        self.fig, self.ax = plt.subplots()
        plt.subplots_adjust(left=0.25, bottom=0.25)

        self._st = stack  # internal reference to the stack

        # Initialize the imshow axis
        self.im0 = int(self._st.shape[0] / 2)  # initial slice to show
        self.axI = self.ax.imshow(stack[self.im0, :, :], **kwargs)

        # Setup the slider
        ax_color = 'lightgoldenrodyellow'
        self.axSlider = plt.axes([0.25, 0.1, 0.65, 0.03], facecolor=ax_color)
        self.sl = Slider(self.axSlider, 'Slice', 0, self._st.shape[0] - 1, valinit=self.im0, valfmt='%1.f')
        self.sl.on_changed(self._update)

        plt.show()

    def _update(self, val):
        num = self.sl.val
        self.axI.set_data(self._st[int(round(num)), :, :])
        self.fig.canvas.draw_idle()

```

--------------------------------

### Initial Correlation Image

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/algo/multicorr_funcs.html

Generates the initial correlation image in Fourier space. Supports 'phase', 'cross', and 'hybrid' methods. Use 'cross' for standard cross-correlation.

```python
import numpy as np

def initial_correlation_image(g1, g2, method='cross', verbose=False):
    """Generate correlation image at initial resolution using the method specified.

    Parameters
    ----------
        g1 : complex ndarray
            Fourier transform of reference image.
        g2 : complex ndarray
            Fourier transform of the image to register (the kernel).
        method : str, optional
            The correlation method to use. Must be 'phase' or 'cross' or 'hybrid' (default = 'cross')
        verbose : bool, default is False
            Print output.
    Returns
    -------
        imageCorr : ndarray complex
            Correlation array which has not yet been inverse Fourier transformed.
    """
    if verbose:
        print('Method is {}'.format(method))
    G12 = g2 * np.conj(g1)  # is this the correct order that we want?
    if method == 'phase':
        imageCorr = np.exp(1j * np.angle(G12))
    elif method == 'cross':
        imageCorr = G12
    elif method == 'hybrid':
        imageCorr = np.sqrt(np.abs(G12)) * np.exp(1j * np.angle(G12))
    else:
        raise TypeError('{} method is not allowed'.format(str(method)))

    return imageCorr
```

--------------------------------

### GetTiltsFromBrukerSequence

Source: https://openncem.readthedocs.io/en/latest/_modules/ncempy/edstomo/bruker.html

Finds Bruker bcf files in a directory and determines their tilt angles based on filenames. Assumes filenames are in the format '...-tilt.bcf'.

```APIDOC
## GetTiltsFromBrukerSequence

### Description
Finds the set of Bruker bcf files and figures out their tilts based on filenames. Assumes filenames are in the format '...-tilt.bcf'.

### Parameters
#### Path Parameters
- **Directory** (str) - Required - Name of directory containing the bcf files.

### Returns
- **list of floats**: A list of tilt angles.
```
Tokens:
Raw