0
# File Input/Output Operations
1

2
Universal file reading and format conversion for multiple electron microscopy file formats. The I/O module provides a unified interface for accessing data from various proprietary microscopy formats while preserving metadata and calibration information.
3

4
## Capabilities
5

6
### Universal File Reader
7

8
Main entry point for reading electron microscopy files. Automatically detects file format and returns structured data with metadata.
9

10
```python { .api }
11
def read(filename: str) -> dict:
12
    """
13
    Universal file reader for electron microscopy formats.
14
    
15
    Parameters:
16
    - filename: str, path to the microscopy data file
17
    
18
    Returns:
19
    dict: Dictionary containing:
20
        - 'data': numpy array of image/spectrum data
21
        - 'pixelSize': list of pixel sizes for each dimension
22
        - 'pixelUnit': list of units for each dimension
23
        - 'pixelOrigin': list of origins for each dimension
24
        - Additional format-specific metadata
25
    """
26
```
27

28
### Digital Micrograph Files
29

30
Support for Gatan Digital Micrograph DM3 and DM4 files with complete tag structure parsing.
31

32
```python { .api }
33
class fileDM:
34
    """
35
    Digital Micrograph file handler.
36
    
37
    Attributes:
38
    - filename: str, path to DM file
39
    - tags: dict, parsed tag structure
40
    - numObjects: int, number of data objects
41
    """
42
    
43
    def __init__(self, filename: str): ...
44
    def getDataset(self, index: int) -> dict: ...
45
    def getSlice(self, slice_obj, mem_map: bool = False): ...
46

47
def dmReader(filename: str) -> dict:
48
    """
49
    Read Digital Micrograph files.
50
    
51
    Parameters:
52
    - filename: str, path to .dm3 or .dm4 file
53
    
54
    Returns:
55
    dict: Data dictionary with image arrays and metadata
56
    """
57
```
58

59
### SER Files
60

61
Support for FEI/Thermo Fisher TIA SER files and associated EMI metadata.
62

63
```python { .api }
64
class fileSER:
65
    """
66
    SER file handler for TIA format.
67
    
68
    Attributes:
69
    - filename: str, path to SER file
70
    - head: dict, file header information
71
    - numObjects: int, number of data objects
72
    """
73
    
74
    def __init__(self, filename: str): ...
75
    def getDataset(self, index: int) -> dict: ...
76
    def getSlice(self, slice_obj, mem_map: bool = False): ...
77

78
def serReader(filename: str) -> dict:
79
    """
80
    Read SER files with EMI metadata.
81
    
82
    Parameters:
83
    - filename: str, path to .ser file
84
    
85
    Returns:
86
    dict: Data dictionary with series data and metadata
87
    """
88

89
def read_emi(filename: str) -> dict:
90
    """
91
    Read EMI metadata file associated with SER.
92
    
93
    Parameters:
94
    - filename: str, path to .emi file
95
    
96
    Returns:
97
    dict: Parsed EMI metadata
98
    """
99

100
class NotSERError(Exception):
101
    """Exception raised when file is not a valid SER file."""
102
```
103

104
### EMD Files
105

106
Support for Electron Microscopy Dataset (EMD) HDF5-based files.
107

108
```python { .api }
109
class fileEMD:
110
    """
111
    EMD file handler for HDF5-based format.
112
    
113
    Attributes:
114
    - filename: str, path to EMD file
115
    - file_hdl: h5py.File, HDF5 file handle
116
    - version: tuple, EMD format version
117
    """
118
    
119
    def __init__(self, filename: str, readonly: bool = True): ...
120
    def get_emdgroup(self, group_number: int): ...
121
    def list_emds(self) -> list: ...
122
    def put_emdgroup(self, group_name: str, data, **kwargs): ...
123

124
def emdReader(filename: str, dset_name: str = None) -> dict:
125
    """
126
    Read EMD files.
127
    
128
    Parameters:
129
    - filename: str, path to .emd file
130
    - dset_name: str, specific dataset name to read
131
    
132
    Returns:
133
    dict: Data dictionary with arrays and metadata
134
    """
135

136
def emdWriter(filename: str, data_dict: dict, **kwargs):
137
    """
138
    Write EMD files.
139
    
140
    Parameters:
141
    - filename: str, output EMD file path
142
    - data_dict: dict, data to write with metadata
143
    """
144

145
class NoEmdDataSets(Exception):
146
    """Exception raised when no EMD datasets found."""
147

148
class UnsupportedEmdVersion(Exception):
149
    """Exception raised for unsupported EMD versions."""
150
```
151

152
### EMD Velox Files
153

154
Support for FEI Velox EMD format files.
155

156
```python { .api }
157
class fileEMDVelox:
158
    """
159
    EMD Velox file handler.
160
    
161
    Attributes:
162
    - filename: str, path to Velox EMD file
163
    - file_hdl: h5py.File, HDF5 file handle
164
    """
165
    
166
    def __init__(self, filename: str): ...
167
    def get_dataset(self, index: int) -> dict: ...
168
    def list_datasets(self) -> list: ...
169

170
def emdVeloxReader(filename: str) -> dict:
171
    """
172
    Read EMD Velox files.
173
    
174
    Parameters:
175
    - filename: str, path to Velox EMD file
176
    
177
    Returns:
178
    dict: Data dictionary with detector data and metadata
179
    """
180
```
181

182
### MRC Files
183

184
Support for Medical Research Council (MRC) format files commonly used in cryo-EM.
185

186
```python { .api }
187
class fileMRC:
188
    """
189
    MRC file handler.
190
    
191
    Attributes:
192
    - filename: str, path to MRC file
193
    - header: dict, MRC header information
194
    """
195
    
196
    def __init__(self, filename: str): ...
197
    def getSlice(self, slice_obj, mem_map: bool = False): ...
198

199
def mrcReader(filename: str) -> dict:
200
    """
201
    Read MRC files.
202
    
203
    Parameters:
204
    - filename: str, path to .mrc file
205
    
206
    Returns:
207
    dict: Volume data with header metadata
208
    """
209

210
def mrcWriter(filename: str, data_dict: dict):
211
    """
212
    Write MRC files.
213
    
214
    Parameters:
215
    - filename: str, output MRC file path
216
    - data_dict: dict, volume data and metadata
217
    """
218

219
def mrc2emd(mrc_file: str, emd_file: str):
220
    """
221
    Convert MRC file to EMD format.
222
    
223
    Parameters:
224
    - mrc_file: str, input MRC file path
225
    - emd_file: str, output EMD file path
226
    """
227

228
def emd2mrc(emd_file: str, mrc_file: str):
229
    """
230
    Convert EMD file to MRC format.
231
    
232
    Parameters:
233
    - emd_file: str, input EMD file path
234
    - mrc_file: str, output MRC file path
235
    """
236
```
237

238
### SMV Files
239

240
Support for Single-image (SMV) format files used in crystallography.
241

242
```python { .api }
243
class fileSMV:
244
    """
245
    SMV file handler.
246
    
247
    Attributes:
248
    - filename: str, path to SMV file
249
    - header: dict, SMV header information
250
    """
251
    
252
    def __init__(self, filename: str): ...
253
    def getSlice(self, slice_obj): ...
254

255
def smvReader(filename: str) -> dict:
256
    """
257
    Read SMV files.
258
    
259
    Parameters:
260
    - filename: str, path to .smv file
261
    
262
    Returns:
263
    dict: Image data with header metadata
264
    """
265

266
def smvWriter(filename: str, data_dict: dict):
267
    """
268
    Write SMV files.
269
    
270
    Parameters:
271
    - filename: str, output SMV file path
272
    - data_dict: dict, image data and metadata
273
    """
274
```
275

276
### DECTRIS Files
277

278
Support for DECTRIS detector format files.
279

280
```python { .api }
281
class fileDECTRIS:
282
    """
283
    DECTRIS file handler.
284
    
285
    Attributes:
286
    - filename: str, path to DECTRIS file
287
    """
288
    
289
    def __init__(self, filename: str): ...
290
```
291

292
## Usage Examples
293

294
### Reading Different File Formats
295

296
```python
297
import ncempy.io
298

299
# Universal reader - automatically detects format
300
data = ncempy.io.read('image.dm4')
301
print(f"Data shape: {data['data'].shape}")
302
print(f"Pixel size: {data['pixelSize']}")
303

304
# Read SER file series
305
ser_data = ncempy.io.read('series.ser')
306
for i, frame in enumerate(ser_data['data']):
307
    print(f"Frame {i}: {frame.shape}")
308

309
# Read EMD with specific dataset
310
emd_data = ncempy.io.emdReader('volume.emd', dset_name='data')
311
```
312

313
### Format Conversion
314

315
```python
316
import ncempy.io
317

318
# Convert MRC to EMD
319
ncempy.io.mrc2emd('volume.mrc', 'volume.emd')
320

321
# Convert EMD to MRC
322
ncempy.io.emd2mrc('volume.emd', 'volume.mrc')
323

324
# Write new EMD file
325
data_dict = {
326
    'data': image_array,
327
    'pixelSize': [1.0, 1.0],
328
    'pixelUnit': ['nm', 'nm']
329
}
330
ncempy.io.emdWriter('output.emd', data_dict)
331
```