0
# File I/O and Format Support
1

2
Comprehensive support for reading and writing various Electronic Design Automation (EDA) file formats with configurable import/export options and format-specific features.
3

4
## Capabilities
5

6
### Supported File Formats
7

8
KLayout supports industry-standard EDA file formats for layout data exchange:
9

10
- **GDS2/GDSII**: Industry standard binary format for IC layouts
11
- **OASIS**: Open Artwork System Interchange Standard
12
- **CIF**: Caltech Intermediate Format
13
- **DXF**: AutoCAD Drawing Exchange Format
14
- **LEF/DEF**: Library Exchange Format and Design Exchange Format
15
- **Magic**: Magic VLSI layout tool format
16
- **Gerber**: PCB manufacturing format (basic support)
17

18
### Loading Layout Files
19

20
```python { .api }
21
class LoadLayoutOptions:
22
    def __init__(self):
23
        """Create default loading options."""
24
    
25
    def select_cell(self, cell_name: str) -> None:
26
        """
27
        Select a specific cell to load (top cell).
28
        
29
        Parameters:
30
        - cell_name: Name of the cell to load as top cell
31
        """
32
    
33
    def select_all_cells(self) -> None:
34
        """Select all cells for loading."""
35
    
36
    def layer_map(self, layer_map: LayerMap) -> None:
37
        """
38
        Set layer mapping for import.
39
        
40
        Parameters:
41
        - layer_map: Mapping between file layers and target layers
42
        """
43
    
44
    def create_other_layers(self, create: bool) -> None:
45
        """
46
        Control whether to create layers not in layer map.
47
        
48
        Parameters:
49
        - create: If True, create unmapped layers automatically
50
        """
51
    
52
    def text_enabled(self, enabled: bool) -> None:
53
        """Enable or disable text import."""
54
    
55
    def properties_enabled(self, enabled: bool) -> None:
56
        """Enable or disable property import."""
57

58
def read_layout(filename: str, options: LoadLayoutOptions = None) -> Layout:
59
    """
60
    Read a layout file and return a Layout object.
61
    
62
    Parameters:
63
    - filename: Path to the layout file
64
    - options: Optional loading configuration
65
    
66
    Returns:
67
    Layout: The loaded layout
68
    """
69

70
# Layout method for reading into existing layout
71
class Layout:
72
    def read(self, filename: str, options: LoadLayoutOptions = None) -> None:
73
        """
74
        Read layout data from file into this layout.
75
        
76
        Parameters:
77
        - filename: Path to the layout file
78
        - options: Optional loading configuration
79
        """
80
```
81

82
### Saving Layout Files
83

84
```python { .api }
85
class SaveLayoutOptions:
86
    def __init__(self):
87
        """Create default saving options."""
88
    
89
    def set_format(self, format: str) -> None:
90
        """
91
        Set output format explicitly.
92
        
93
        Parameters:
94
        - format: Format name ("GDS2", "OASIS", "CIF", "DXF", etc.)
95
        """
96
    
97
    def select_cell(self, cell_index: int) -> None:
98
        """
99
        Select specific cell to save as top cell.
100
        
101
        Parameters:
102
        - cell_index: Index of cell to save
103
        """
104
    
105
    def add_layer(self, layer_index: int, layer_info: LayerInfo) -> None:
106
        """
107
        Add layer to output with specific layer info.
108
        
109
        Parameters:
110
        - layer_index: Internal layer index
111
        - layer_info: Target layer specification
112
        """
113
    
114
    def scale_factor(self, factor: float) -> None:
115
        """
116
        Set coordinate scaling factor.
117
        
118
        Parameters:
119
        - factor: Scaling factor for coordinates
120
        """
121
    
122
    def write_context_info(self, write: bool) -> None:
123
        """Enable writing of context information."""
124
    
125
    def write_file_properties(self, write: bool) -> None:
126
        """Enable writing of file-level properties."""
127

128
# Layout method for saving
129
class Layout:
130
    def write(self, filename: str, options: SaveLayoutOptions = None) -> None:
131
        """
132
        Write layout data to file.
133
        
134
        Parameters:
135
        - filename: Output file path
136
        - options: Optional save configuration
137
        """
138
```
139

140
### Layer Mapping
141

142
```python { .api }
143
class LayerMap:
144
    def __init__(self):
145
        """Create empty layer mapping."""
146
    
147
    def map(self, source: LayerInfo, target: LayerInfo) -> None:
148
        """
149
        Map source layer to target layer.
150
        
151
        Parameters:
152
        - source: Source layer specification
153
        - target: Target layer specification
154
        """
155
    
156
    def map_expr(self, source_expr: str, target: LayerInfo) -> None:
157
        """
158
        Map layers using expression to target layer.
159
        
160
        Parameters:
161
        - source_expr: Layer selection expression
162
        - target: Target layer specification
163
        """
164
    
165
    def unmap(self, source: LayerInfo) -> None:
166
        """Remove mapping for source layer."""
167
    
168
    def clear(self) -> None:
169
        """Clear all mappings."""
170

171
class LayerInfo:
172
    def __init__(self, layer: int, datatype: int = 0, name: str = ""):
173
        """
174
        Layer specification with layer number, datatype, and optional name.
175
        
176
        Parameters:
177
        - layer: Layer number
178
        - datatype: Datatype number (default 0)
179
        - name: Optional layer name
180
        """
181
    
182
    layer: int
183
    datatype: int
184
    name: str
185
    
186
    def is_named(self) -> bool:
187
        """Check if layer has a name."""
188
```
189

190
### Format-Specific Options
191

192
#### GDS2 Options
193

194
```python { .api }
195
class GDS2WriterOptions:
196
    def write_timestamps(self, write: bool) -> None:
197
        """Enable writing of timestamps."""
198
    
199
    def write_cell_properties(self, write: bool) -> None:
200
        """Enable writing of cell properties."""
201
    
202
    def libname(self, name: str) -> None:
203
        """Set library name in GDS2 header."""
204
    
205
    def user_units(self, units: float) -> None:
206
        """Set user units (typically 1e-6 for micrometers)."""
207
    
208
    def database_units(self, units: float) -> None:
209
        """Set database units (typically 1e-9 for nanometers)."""
210
```
211

212
#### OASIS Options
213

214
```python { .api }
215
class OASISWriterOptions:
216
    def compression_level(self, level: int) -> None:
217
        """
218
        Set compression level (0-9).
219
        
220
        Parameters:
221
        - level: Compression level (0=none, 9=maximum)
222
        """
223
    
224
    def write_cblocks(self, write: bool) -> None:
225
        """Enable writing of compressed blocks."""
226
    
227
    def strict_mode(self, strict: bool) -> None:
228
        """Enable strict OASIS compliance mode."""
229
```
230

231
## Usage Examples
232

233
### Basic File Operations
234

235
```python
236
import klayout.db as db
237

238
# Read a GDS file
239
layout = db.Layout()
240
layout.read("input.gds")
241

242
# Process layout...
243

244
# Write to different format
245
layout.write("output.oas")  # OASIS format
246
layout.write("output.cif")  # CIF format
247
```
248

249
### Advanced Loading with Options
250

251
```python
252
import klayout.db as db
253

254
# Create loading options
255
options = db.LoadLayoutOptions()
256

257
# Only load specific cell
258
options.select_cell("TOP_CELL")
259

260
# Create layer mapping
261
layer_map = db.LayerMap()
262
layer_map.map(db.LayerInfo(1, 0), db.LayerInfo(10, 0))  # Map layer 1/0 to 10/0
263
layer_map.map(db.LayerInfo(2, 0), db.LayerInfo(11, 0))  # Map layer 2/0 to 11/0
264
options.layer_map(layer_map)
265

266
# Disable text import
267
options.text_enabled(False)
268

269
# Load with options
270
layout = db.Layout()
271
layout.read("complex_design.gds", options)
272
```
273

274
### Selective Cell Export
275

276
```python
277
import klayout.db as db
278

279
layout = db.Layout()
280
layout.read("large_design.gds")
281

282
# Find specific cell
283
cell = layout.cell("MEMORY_BLOCK")
284

285
# Create save options for specific cell
286
options = db.SaveLayoutOptions()
287
options.select_cell(cell.cell_index)
288

289
# Add only specific layers
290
layer1 = layout.layer(db.LayerInfo(1, 0))
291
layer2 = layout.layer(db.LayerInfo(2, 0))
292
options.add_layer(layer1, db.LayerInfo(1, 0))
293
options.add_layer(layer2, db.LayerInfo(2, 0))
294

295
# Save only the selected cell and layers
296
layout.write("memory_block_only.gds", options)
297
```
298

299
### Format Conversion with Scaling
300

301
```python
302
import klayout.db as db
303

304
# Read layout in database units
305
layout = db.Layout()
306
layout.read("design_in_nm.gds")
307

308
# Create save options with scaling
309
options = db.SaveLayoutOptions()
310
options.scale_factor(0.001)  # Convert from nm to μm
311

312
# Write with scaling
313
layout.write("design_in_um.gds", options)
314
```
315

316
### Layer Management During I/O
317

318
```python
319
import klayout.db as db
320

321
# Create complex layer mapping
322
layer_map = db.LayerMap()
323

324
# Map multiple source layers to single target
325
layer_map.map(db.LayerInfo(1, 0), db.LayerInfo(100, 0))
326
layer_map.map(db.LayerInfo(1, 1), db.LayerInfo(100, 0))  # Merge datatypes
327

328
# Map named layers
329
layer_map.map(db.LayerInfo(0, 0, "METAL1"), db.LayerInfo(10, 0))
330
layer_map.map(db.LayerInfo(0, 0, "METAL2"), db.LayerInfo(20, 0))
331

332
# Use expression mapping
333
layer_map.map_expr("1/*", db.LayerInfo(100, 0))  # All datatypes of layer 1
334

335
options = db.LoadLayoutOptions()
336
options.layer_map(layer_map)
337
options.create_other_layers(False)  # Don't create unmapped layers
338

339
layout = db.Layout()
340
layout.read("input_with_many_layers.gds", options)
341
```
342

343
### Working with File Properties
344

345
```python
346
import klayout.db as db
347

348
# Read layout and access file properties
349
layout = db.Layout()
350
layout.read("design_with_properties.gds")
351

352
# Check for properties on layout
353
if layout.properties_id() != 0:
354
    props = layout.properties(layout.properties_id())
355
    print("Layout properties:", props)
356

357
# Write with properties enabled
358
options = db.SaveLayoutOptions()
359
options.write_file_properties(True)
360
options.write_context_info(True)
361

362
layout.write("output_with_properties.gds", options)
363
```