[Artwork] / [QisMLib] / [Programmer's Corner]

ClipExtract

Command-line program to extract in parallel threads, lots of tiny clips of data from a GDSII/OASIS/DBLOAD design to GDSII/OASIS/TIFF/BMP/RAW files on disk

Command-line reference

clipextract +input:{input_file_path} +outdir:{output_directory} [FILE-OPTIONS] 
  {WINDOW-SPEC} {FORMAT} [FORMAT-OPTIONS] [MISC-OPTIONS]

Required

+input:{input_file_path}

• Specify a valid GDSII/OASIS/DBLOAD file to extract clips from

+outdir:{output_directory}

• Specify the path of a directory where the output files will be created
• The output directory MUST exist prior to executing clipextract

WINDOW-SPEC

• Specify at least one window using one or more of the following specifications

-window:LLUR:{name}:{llx},{lly},{urx},{ury}

• Specify a window using it's lower left and upper right co-ordinates (in file units)
• The {name} is used to identify the window and the file generated thereof
• Final output path = {output_directory} + {name} + {extension}

-window:LLWH:{name}:{llx},{lly},{width},{height}

• Specify a window using it's lower left co-ordinates, width and height (in file units)
• The {name} is used to identify the window and the file generated thereof
• Final output path = {output_directory} + {name} + {extension}

-window:CWH:{name}:{cx},{cy},{width},{height}

• Specify a window using it's center co-ordinates, width and height (in file units)
• The {name} is used to identify the window and the file generated thereof
• Final output path = {output_directory} + {name} + {extension}

@window:LLUR:{name}:{window_list_file}

• Read a set of windows from a text file located at {window_list_file}
• Each line in that file specifies a single window as {llx},{lly},{urx},{ury} (in file units)
• Lines beginning with a # are treated as comments
• The {name} is used to identify the windows and the files generated thereof
• Final output path = {output_directory} + {name} + {line_number} + {extension}

@window:LLWH:{name}:{window_list_file}

• Read a set of windows from a text file located at {window_list_file}
• The first line specifies the {width},{height} (in file units) to be used for all windows
• Each subsequent line in that file specifies the lower left co-ordinate (in file units) where a single window is to be placed
• Lines beginning with a # are treated as comments
• The {name} is used to identify the windows and the files generated thereof
• Final output path = {output_directory} + {name} + {line_number} + {extension}

@window:CWH:{name}:{window_list_file}

• Read a set of windows from a text file located at {window_list_file}
• The first line specifies the {width},{height} (in file units) to be used for all windows
• Each subsequent line in that file specifies the co-ordinates a point (in file units) where the center of a window is to be placed
• Lines beginning with a # are treated as comments
• The filename is used to identify the windows and the files generated thereof
• Final output path = {output_directory} + {name} + {line_number} + {extension}

-tile:RXY:{name}:{roi_llx},{roi_lly},{roi_urx},{roi_ury}:{nx},{ny}[:{i},{j}]*

• Generate {nx} x {ny} same sized tiles from a region defined by it's lower left and upper right co-ordinates (in file units)
• Optionally, if a set of {i},{j} tile positions (1 <= I <= {nx} and 1 <= J <= {ny})are specified, only those tiles will be extracted. Otherwise, all tiles will be extracted
• The filename is used to identify the windows and the files generated thereof
• Final output path = {output_directory} + {name} + {I}.{J} + {extension}

-tile:RWH:{name}:{roi_llx},{roi_lly},{roi_urx},{roi_ury}:{width},{height}[:{i},{j}]*

• Generate {width} x {height} same sized tiles from a region defined by it's lower left and upper right co-ordinates (in file units)
• Optionally, if a set of {i},{j} tile positions (1 <= I <= Num. tiles in X and 1 <= J <= Num. tiles in Y)are specified, only those tiles will be extracted. Otherwise, all tiles will be extracted
• The filename is used to identify the windows and the files generated thereof
• Final output path = {output_directory} + {name} + {I}.{J} + {extension}

-tile:CWH:{name}:{width},{height}:{cx},{cy}[:{cx},{cy}]*

• Generate {width} x {height} sized tiles centered at one or more co-ordinates
• The filename is used to identify the windows and the files generated thereof
• Final output path = {output_directory} + {name} + {counter} + {extension}

FORMAT

+format:IMAGE

• Extract a raster image for each window and do not write them to disk

+format:TIFF

• Extract a raster image for each window and write them to disk as monochrome TIFF images (with packbits compression)

+format:BMP

• Extract a raster image for each window and write them to disk as monochrome BMP images (uncompressed) (top-down)

+format:VBMP

• Extract a raster image for each window and write them to disk as monochrome BMP images (uncompressed) (bottom-up)

+format:RAW

• Extract a raster image for each window and write them to disk as Artwork's RAW format

+format:GDSII

• Extract polygon vectors from each window and write them to disk as a GDSII file (flat cell hierarchy, layers preserved)

+format:OASIS

• Extract polygon vectors from each window and write them to disk as an OASIS file (flat cell hierarchy, layers preserved, minimal compression)

+format:POLYS

• Extract polygon vectors from each window and do not write them to disk

Optional

FILE-OPTIONS

-layers:{layer_list}

• Specify a comma-separated list of layer and/or layer:datatype to be loaded prior to extraction
• e.g -layers:1,2:2,3,4:4,4:5
• If the datatype is omitted, all the datatypes for the corresponding layer will be loaded
• Any layer:datatype that does not match this specification will be filtered out
• By default, all the layers in the file are loaded
• Overrides preceding -layermap:

-layermap:{layer-mapping}

• Specify a layer mapping for extraction (vectors)

• xxxxxxxxxx
  {layer-mapping} := [ALL-NULL][,{from}-{to}]+
    where {from},{to} := {layer}[:{datatype}]
  e.g -layermap:1-3 (move layers 1:* to 3:*, all other layers extracted as-is)
      -layermap:1-3:0 (move layers 1:* to 3:0, all other layers extracted as-is)
      -layermap:1:0-3:0 (move 1:0 to 3:0, all other layers extracted as-is)
      -layermap:ALL-NULL,1-3 (move layers 1:* to 3:*, drop all other layers)
      -layermap:ALL-NULL,1-1 (drop all layers except 1:*) (same as -layers:1)
  

• Overrides preceding -layers:

-cell:{cell}

• Specify the name of the cell to be used as the view cell from which clips will be extracted
• By default, the deepest top cell is used as the view cell

-loadfromdisk

• Throughout the execution of clipextract, access data from the file on disk
• This reduces the overall memory footprint of the program at the cost of slower operation
• By default, the file is loaded into memory at start and all the access is memory based in order to get the fastest performance

FORMAT-OPTIONS for raster images

-pixelsize:{size_x}[,{size_y}]

• Specify the size of a pixel (in file units) along X or X,Y
• If the second value is omitted, the X-value is used to draw a square pixel
• By default, a square pixel of 1.0 file units is used

-dither:{0.0-TO-1.0}

• Specify a value for ordered dithering using a 8x8 Bayer matrix.
• The number of pixels drawn in a 8x8 pixel block for solid fill areas decreases as the dither value changes from 1.0 (all pixels) to 0.0 (no pixels)
• By default, all pixels are drawn (1.0)

-invert

• Invert the image polarity by drawing white pixels (data) on a black background
• By default, we draw black pixels (data) on a white background

-right-to-left

• Reverse the direction of rasterization along a single row of pixels. The rightmost pixel on a given row corresponds to the min-x position in the data space
• By default, the rightmost pixel on a given row corresponds to the max-x position in the data space

-bottom-to-top

• Reverse the direction of rasterization along the Y direction. With this option, the first row of pixels represents the min-y co-ordinates in data space
• By default, the first row of pixels in the image represent the max-y co-ordinates in data-space (top to bottom)

FORMAT-OPTIONS for extracting polygons

-union

• Unionize the polygon vectors such that polygons containing holes are split into butting polygons
• Refer to to this page for more information on butting polygons

-clip

• Polygons crossing the window are clipped at the window edges and polygons with holes are split into butting polygons
• By default, any polygon crossing the window is extracted as-is

-maxvert:{max_vert_per_polygon}

• Specify the maximum number of vertices per output polygon (only if -clip, -union or -lsynth are used)
• Polygons with vertices more than the specified limit will be split into smaller adjoining polygons
• Default max: 8190 vertices

-butting:{overlap}

• If specified, polygons with holes are split into butting polygons. The overlap value if > 0.0 determines the amount of overlap in file units between those polygons along the butting edges
• By default, polygons with holes are outputted with cutlines joining the hole boundaries to the outer boundary

-lsynth:{layer_synth_spec}

• Create new layers (polygons) by performing boolean operations on two or more layers (polygons)
• Refer to Layer Synthesis Spec. (below) for detailed syntax
• The output clips do not have any hierarchy
• -union option is ignored in this mode

MISC-OPTIONS

-thrnum:{n_window_threads},{n_threads_per_window}

• Specify the number of threads to be used for collecting polygons (exploder) and processing them (processor)
• The number of exploder threads determines the number of windows being extracted at the same time
• The number of processor threads determined how much parallelism is applied into generating the output for each window (computing union). The rasterization is always single threaded since each polygon is rasterized as soon as it is retrieved from the database (on-the-fly)
• By default, the configuration used is 2,(number of physical cores)/2 for extracting polygons and (number of physical cores),1 for extracting images

-log:{log_path}] or -log+:{log_path}

• Generate an execution log (text file) or append to an existing text file

-silent

• Do not send progress updates to stdout/stderr. Doing so might result in slight improvement in execution time
• By default, clipextract prints messages and progress updates to stdout/stderr

Layer Synthesis Spec.

Linear syntax

xxxxxxxxxx
+ {layersynth-spec} := {target}[;{target}]* (One or more targets)
+ {target} := {target-layer}:{target-dttp}={op-layer}[:{op-dttp}] [{op}{op-layer}[:{op-dttp}]]* 
  (Generate a layer:dttp from operations on one or more layers or layer:dttps)
+ {op} := '+' (union) or '-' (difference) or '&' (intersection) or '^' (xor) or ',' (aggregation/OR-without-union) or '|' (aggregation/OR-without-union)

• All {target-layer}:{target-dttp} will be outputted
• Any hierarchy if present in the input is flattened

Examples: 100:0=2,5:0,7 (aggregate polygons on 2:* 5:0 and 7:* into a new layer 100:0) 100:0=2+5:0+7 (unionize polygons on 2:* 5:0 and 7:* into a new layer 100:0) 100:0=2+5:0-7 (unionize polygons on 2:* 5:0 and then subtract 7:* to create a new layer 100:0) 100:0=2,5:0-7 (aggregate polygons on 2:* 5:0 and then subtract 7:* to create a new layer 100:0) 100:0=2^5 (Compute XOR between 2:* and 5:* as 100:0) 100:0=2&5 (Compute INTERSECTION between 2:* and 5:* as 100:0) 100:0=2+5;200:0=100:0-5;300:0=200^5;400:0=300&5 (Create multiple synthesized layers from multiple operations between layers)

Postfix syntax

xxxxxxxxxx
+ {layersynth-spec} := @{target}[{target}]*
+ {target} := {operations}{result}
+ {operations} := list of postfix operations resulting in ONE output. E.g:
  "L" (single layer all datatypes (A:*)) (0 <= L < 65535)
  "L:D" (single layer:datatype) (0 <= L,D < 65535)
  "A B +" (UNIONIZE A and B) (A,B can be of type L or L:D)
  "A B -" (SUBTRACT B from A)
  "A A ^" (XOR of A and B)
  "A B &" (INTERSECTION of A and B)
  "A B |" (Combine A and B without union)
  "A C =" (Assing A to C where C is of type L:D)
  "A B - C D & +" (same as (A - B) + (C & D))
  "A B - C & D +" (same as ((A - B) & C) + D)
  + Not allowed:
    "A B - C D &" (because it results in TWO outputs A - B and C & D)
+ {result} := Can be one of the following
  "R ~" (Emit the result as a new layer R where R is of type L:D, 0 <= L,D < 65535)
  "R *" (Unionize the result and emit it as a new layer R)

Example: "@1 2:2 - 3:3 4 | & 0:0 ~"

• First subtract 2:2 from 1:* (save the result to A)
• Then, combine 3:3 and 4:* (save the result to B)
• Intersect A and B (save the result to C)
• Output C as 0:0

"@1 2 ^ 100:0 = 0:0 ~ 3 4 | 200:0 = 0:1 * 100:0 200:0 & 0:3 ~"

• First xor 1:* and 2:* and save the result to 100:0
• Next, emit the result as 0:0
• New expression, combine 4:* and 3:* and save that as 200:0
• Next, unionize the result and emit as 0:1
• Finally, intersect 100:0 with 200:0 and emit the result as 0:3