[Artwork] / [QisMLib]

QisMRaster Extension

A QisMLib extension to generate high-resolution monochrome bitmaps from CAD data

QisMRaster C++ API (qismraster.h)

QisMRasterFlags

All the flags (enumerated constants) associated with the QisMRaster API

xxxxxxxxxx
struct QisMRasterFlags { ... };

ImageFormat

• Flags that represent an image file format on disk

• IFF_BUF implies no formatting/writing to disk

• IFF_TIFF implies TIF format with packbits compression

• IFF_TIF8 implies extended TIF (Big TIF) format with packbits compression. See here

• IFF_BMP implies a top down (max-y on top) uncompressed BMP file

• IFF_VBMP implies a bottom up (min-y on top) uncompressed BMP file

• IFF_RAW implies Artwork's RAW file format. See here for details

xxxxxxxxxx
enum ImageFormat {
   IFF_BUF=0 
  ,IFF_TIFF=1 
  ,IFF_BMP=2 
  ,IFF_RAW=3 
  ,IFF_VBMP=4 
  ,IFF_TIF8=5 
};

RasterMode

• Flags that represent how a polygon is rasterized

• RMF_SOLID implies all the pixels on/inside the polygon edges are filled

• RMF_OUTLINE implies only the pixels on the polygon edges are filled Overlapping polygons are NOT unionized. Therefore, interiors of polygons may be filled by edges of other overlapping polygons

xxxxxxxxxx
enum RasterMode {
   RMF_SOLID=0 
  ,RMF_OUTLINE=1 
};

OverlayMode

• Polygon overlay mode (Paint = Foreground fill i.e white if inverted, black otherwise. Scratch = Background fill i.e black if inverted, white otherwise)

• OMF_DITHER implies paint the polygons with the specified dither value

• OMF_PAINT implies paint the polygons regardless of the dither value (same as dither = 1.0)

• OMF_SCRATCH implies scratch the polygons regardless of the dither value (same as dither = 1.0)

xxxxxxxxxx
enum OverlayMode {
  OMF_DITHER=1 
 ,OMF_PAINT=2 
 ,OMF_SCRATCH=3 
};

Grayscale_modes

• Supported gray scale modes

• expressed as GSM_{sample_x}x{sample_y}_{bits_per_px}BPP

• See Create_grayscale

xxxxxxxxxx
enum Grayscale_modes {
  GSM_1x1_1BPP=0 
 ,GSM_2x2_2BPP   
 ,GSM_2x2_4BPP   
 ,GSM_2x2_8BPP   
 ,GSM_4x4_4BPP   
 ,GSM_4x4_8BPP   
 ,GSM_8x8_8BPP   
};

QisMRasterImage

Interface to retrive information about a raster image

xxxxxxxxxx
class QisMRasterImage { ... };

Version control (QisMRasterImage)

• Cast this pointer to any other version (base/derived)

• The version number is embedded in the class name in form of a suffix V<number>

• Get the latest version number supported by this implementation

xxxxxxxxxx
virtual const char* QisMRasterImage_name(const int version) const = 0;
virtual void* QisMRasterImage_cast(const int version) = 0;
virtual const void* QisMRasterImage_cast(const int version) const = 0;
virtual int QisMRasterImage_latest_version() const = 0;

Image_name

• Get the name/path assigned to this image

xxxxxxxxxx
virtual const char* Image_name() const = 0;

Image_buffer

• Get the address of the memory buffer that holds the raster image

xxxxxxxxxx
virtual const unsigned char* Image_buffer() const = 0;

Image_size_bytes

• Get the size of the raster image buffer in bytes

xxxxxxxxxx
virtual long long Image_size_bytes() const = 0;

Polygon_count

• Get the total number of polygons involved in generating this image

xxxxxxxxxx
virtual long long Polygon_count() const = 0;

Vertex_count

• Get the total number of polygon vertices involved in generating this image

xxxxxxxxxx
virtual long long Vertex_count() const = 0;

Rip_time_sec

• Get elapsed time for generating this image

xxxxxxxxxx
virtual double Rip_time_sec() const = 0;

Width_px

Height_px

• Get the width and height of the image in pixels

xxxxxxxxxx
virtual unsigned int Width_px() const = 0;
virtual unsigned int Height_px() const = 0;

Extents_llx

Extents_lly

Extents_urx

Extents_ury

• Get the extents of the data (in file units) corresponding to this image

xxxxxxxxxx
virtual double Extents_llx() const = 0;
virtual double Extents_lly() const = 0;
virtual double Extents_urx() const = 0;
virtual double Extents_ury() const = 0; 

Inverted

• Check if the image polarity is inverted (bits representing data are 0)

xxxxxxxxxx
virtual bool Inverted() const = 0;

Get_dither

• Get the dithering value (using 8x8 bayer matrix)

xxxxxxxxxx
virtual double Get_dither() const = 0;

Get_pixelsize_x

Get_pixelsize_y

• Get size of a pixel along X and Y axes in file units

xxxxxxxxxx
virtual double Get_pixelsize_x() const = 0;
virtual double Get_pixelsize_y() const = 0;

DPI_x

DPI_y

• Get the image resolution along X and Y axes in dots-per-inch

xxxxxxxxxx
virtual double DPI_x() const = 0;
virtual double DPI_y() const = 0;

Get_right_to_left

• Check if the image was rasterized from right to left. If so, the minX of the data occurs on the RHS of the raster image

xxxxxxxxxx
virtual bool Get_right_to_left() const = 0;

Report

• Get all of the information about this image as a pre-formatted string

xxxxxxxxxx
virtual const char* Report() const = 0;

QisMRasterImageV2

Extension for QisMRasterImage (version = 2)

xxxxxxxxxx
class QisMRasterImageV2: public QisMRasterImage { ... };

Get_bottom_to_top

• Returns true if the min-y data appears at the top of the image

xxxxxxxxxx
virtual bool Get_bottom_to_top() const = 0;

QisMRasterNotify

Interface to recieve raster images via a callback for certain multi-window rasterization operations

xxxxxxxxxx
class QisMRasterNotify { ... };

Version control (QisMRasterNotify)

• Cast this pointer to any other version (base/derived)

• The version number is embedded in the class name in form of a suffix V<number>

• Get the latest version number supported by this implementation

xxxxxxxxxx
virtual const char* QisMRasterNotify_name() const = 0;
virtual void* QisMRasterNotify_cast(const int version) = 0;
virtual const void* QisMRasterNotify_cast(const int version) const = 0;
virtual int QisMRasterNotify_latest_version() const = 0;

On_qismraster_image

Get_qismraster_image_proc_error_msg

• Receive a raster image for a specified window

• img is a handle to the newly generated image

• thread_lock is a handle to a mutex specified by the calling application

• This callback may be generated by multiple threads simultaneously. Please ensure proper protection of shared data during this callback

• Return 0 to continue. Otherwise return an error code and set the error message made available to Get_qismraster_image_proc_error_msg

xxxxxxxxxx
virtual int On_qismraster_image(
  const QisMRasterImage* img, NsQisMLib::QisMThreadLock* thread_lock
  ) { return 0; }
virtual const char* Get_qismraster_image_proc_error_msg() const { return ""; }

QisMRasterNotifyV2

Extension to QisMRasterNotify (version = 2)

xxxxxxxxxx
class QisMRasterNotifyV2: public QisMRasterNotify { ... };

Pre_qismraster_image

• Signals that an image is about to be rasterized

• img_name is the specified name of the image

• lx .. uy is the region of interest

• handle is the rasterizer assigned to perform rasterization

• opts are the rasterization parameters applied

• thread_lock is the mutex that was specified

• Only applies to queue based multi-window rasterization functions *win_queue* of QisMRaster

xxxxxxxxxx
virtual void Pre_qismraster_image(
  const char* img_name, const double lx, const double ly, const double ux, 
  const double uy, QisMRasterizer* handle, const QisMRasterParams* opts, 
  NsQisMLib::QisMThreadLock* thread_lock
  ) { }

QisMRasterNotifyV3

Extension to QisMRasterNotify (version = 3)

xxxxxxxxxx
class QisMRasterNotifyV3: public QisMRasterNotify { ... };

Rasterization_refresh

• In the midst of rasterization, an opportunity for the application to --

  • Refresh the GUI

  • Check status of resources

  • Signal the terminatation of rasterization

• Return 0 to continue the rasterization, non-zero code to terminate (the code will appear in the error message)

xxxxxxxxxx
virtual int Rasterization_refresh() { return 0; }

QisMRasterSubSampler

Interface to a 2x2 down-sampled raster image

xxxxxxxxxx
class QisMRasterSubSampler { ... };

Version control (QisMRasterSubSampler)

• Cast this pointer to any other version (base/derived)

• The version number is embedded in the class name in form of a suffix V<number>

• Get the latest version number supported by this implementation

xxxxxxxxxx
virtual const char* QisMRasterSubSampler_name(const int version) const = 0;
virtual void* QisMRasterSubSampler_cast(const int version) = 0;
virtual const void* QisMRasterSubSampler_cast(const int version) const = 0;
virtual int QisMRasterSubSampler_latest_version() const = 0;

Get_last_error_msg (QisMRasterSubSampler)

• Get error information for any of the sub-sampler operations

xxxxxxxxxx
virtual const char* Get_last_error_msg() const = 0;

Write_to_disk

• Write the sub-sampled image to disk in the specified file format

• file_path is the base (dir + name) of the output file. Extension is added automatically based on the format

• format is one of QisMRasterFlags::ImageFormat

• thrnum is the number of threads to be used for formatting

• Returns true on success. Otherwise call Get_last_error_msg for error information

xxxxxxxxxx
virtual bool Write_to_disk(const char* file_path, const int format, const int thrnum) = 0;

Get_image (QisMRasterSubSampler)

• Get the handle to the underlying sub-sampled image in a format usable with other QisMRaster operations

xxxxxxxxxx
virtual QisMRasterImage* Get_image() = 0;
virtual const QisMRasterImage* Get_image() const = 0;

Detach_buffer (QisMRasterSubSampler)

Destroy_subsampled_buffer

• Detach the underlying raster buffer from the sub-sampler object and take full ownership of it

• The detached buffer MUST be eventually destroyed by the client since it's not managed by the sub-sampler object anymore

xxxxxxxxxx
virtual unsigned char* Detach_buffer(long long& img_sz_) = 0;
virtual void Destroy_subsampled_buffer(unsigned char* buffer) = 0;

QisMGrayscaleImage

Interface to work with a newly generated gray scale image

xxxxxxxxxx
class QisMGrayscaleImage { ... };

Version control (QisMGrayscaleImage)

• Cast this pointer to any other version (base/derived)

• The version number is embedded in the class name in form of a suffix V<number>

• Get the latest version number supported by this implementation

xxxxxxxxxx
virtual const char* QisMGrayscaleImage_name(const int version) const = 0;
virtual void* QisMGrayscaleImage_cast(const int version) = 0;
virtual const void* QisMGrayscaleImage_cast(const int version) const = 0;
virtual int QisMGrayscaleImage_latest_version() const = 0;

Get_buffer

• Get the image buffer

• DO NOT destroy this buffer unless detached

xxxxxxxxxx
virtual unsigned char* Get_buffer() = 0; 
virtual const unsigned char* Get_buffer() const = 0;

Get_buffer_size

• Get the image size in bytes

xxxxxxxxxx
virtual long long Get_buffer_size() const = 0;

Get_row_size_px

• Get the row size in pixels

xxxxxxxxxx
virtual unsigned int Get_row_size_px() const = 0;

Get_row_size_bytes

• Get the row size in bytes

xxxxxxxxxx
virtual unsigned int Get_row_size_bytes() const = 0;

Get_row_count

• Get the no. rows

xxxxxxxxxx
virtual unsigned int Get_row_count() const = 0;

Get_sample_rate

• Get the sampling rate (uniform in X and Y)

xxxxxxxxxx
virtual unsigned int Get_sample_rate() const = 0;

Get_bits_per_px

• Get the no. bits per pixel used to encode the gray value

xxxxxxxxxx
virtual unsigned int Get_bits_per_px() const = 0;

Get_dpi_x

Get_dpi_y

• Get the image dpi along X and Y

xxxxxxxxxx
virtual double Get_dpi_x() const = 0;
virtual double Get_dpi_y() const = 0;

Write_to_disk

• Write the gray scale image as a formatted file on disk

• base_path represents the {file_name} and {directory} for the output. Extension will be automatically added as follows:

  • TIF - .tif

  • TIF8 - .tif8

  • BMP - .bmp

  • VBMP - .bmp

• format is one of the supported file formats. See QisMRasterFlags::ImageFormat

• Also, see QisMRasterFlags::Grayscale_modes for understanding which formats support the specified gray scale mode

• On success, returns true

xxxxxxxxxx
virtual bool Write_to_disk(
  const char* base_path, const int format, const int thrnum
  ) = 0;

Detach_buffer

• De-couple the image buffer for control and use elsewhere

• The image buffer MUST be explicitly destroyed by calling Destroy_grayscale_buffer

xxxxxxxxxx
virtual unsigned char* Detach_buffer(long long& buf_sz) = 0;

QisMRasterParams

A data structure to specify various rasterization options

xxxxxxxxxx
class QisMRasterParams { ... };

Reset (QisMRasterParams)

• Reset the options to default values

xxxxxxxxxx
virtual void Reset() = 0;

Version control (QisMRasterParams)

• Cast this pointer to any other version (base/derived)

• The version number is embedded in the class name in form of a suffix V<number>

• Get the latest version number supported by this implementation

xxxxxxxxxx
virtual const char* QisMRasterParams_name(const int version) const = 0;
virtual void* QisMRasterParams_cast(const int version) = 0;
virtual const void* QisMRasterParams_cast(const int version) const = 0;
virtual int QisMRasterParams_latest_version() const = 0;

Set_pixelsize

Get_pixelsize_x

Get_pixelsize_y

• Set/Get image resolution in terms of size of a pixel in file units

• Default: 1.0 file unit along X and Y

xxxxxxxxxx
virtual void Set_pixelsize(const double xSize, const double ySize) = 0;
virtual double Get_pixelsize_x() const = 0;
virtual double Get_pixelsize_y() const = 0;

Set_invert

Get_invert

• Set/Get image polarity. If true, data bits in the image are 0 and non-data bits are 1. Default: false

xxxxxxxxxx
virtual void Set_invert(const bool set = true) = 0;
virtual bool Get_invert() const = 0;

Set_dither

Get_dither

• Set/Get dithering value (0.0 - 1.0) using a 8x8 bayer matrix

• Default: 1.0.

• A value of 1.0 will result in 1 pixel for every single data bit. A value of 0.0 will set all data bits to background

xxxxxxxxxx
virtual void Set_dither(const double value) = 0;
virtual double Get_dither() const = 0;

Set_right_to_left

Get_right_to_left

• Set/Get the rasterization direction.

• If true, rasterization occurs from right to left so that the minX of the data is found on the RHS of the image.

• No change in the Y direction.

• Default: false

xxxxxxxxxx
virtual void Set_right_to_left(const bool set = true) = 0;
virtual bool Get_right_to_left() const = 0;

Set_est_polygon_buffer_count

Get_est_polygon_buffer_count

• Set/Get the estimated size of the polygon buffer.

• As soon as the polygon buffer is full, it is rasterized and flushed before more any polygons are collected. This way, the polygon buffer can be pre-allocated for superior performance.

• If the polygon buffer size is 0, each polygon is rasterized as it is received (on-the-fly). This makes the rasterization single threaded and may be suitable for small polygon sets.

• Default: 1,000,000 vertices

xxxxxxxxxx
virtual void Set_est_polygon_buffer_count(const long long numVertices) = 0;
virtual long long Get_est_polygon_buffer_count() const = 0;

Set_pattern_recognition

Get_pattern_recognition

• Enable/Disable pattern recognition.

• If enabled, rasterization is optimized for cell references that repeat within the specified window.

• This could save a lot of computations and therefore speed up the rasterization.

• Default: Enabled (true)

xxxxxxxxxx
virtual void Set_pattern_recognition(const bool set = true) = 0;
virtual bool Get_pattern_recognition() const = 0;

Set_image_format

Get_image_format

• Set/Get the image format (See QisMRasterFlags::ImageFormat)

xxxxxxxxxx
virtual void Set_image_format(const QisMRasterFlags::ImageFormat format) = 0;
virtual QisMRasterFlags::ImageFormat Get_image_format() const = 0;

Set_num_threads

Get_num_threads

• Set/Get the number of threads to be used for rasterization.

• If thrnum == 0, the optimal number of threads is automatically set based on the number of processors in the system.

• If thrnum == 1, all polygons are rasterized on-the-fly (no buffering).

• If thrnum > 1, polygons are collected in a buffer (upto Get_est_polygon_buffer_count) before being rasterized.

• Default: 0 (Auto- compute)

xxxxxxxxxx
virtual void Set_num_threads(const int thrnum) = 0;
virtual int Get_num_threads() const = 0;

Set_raster_mode

Get_raster_mode

• Set/Get raster mode. Default: QisMRasterFlags::RMF_SOLID

xxxxxxxxxx
virtual void Set_raster_mode(const QisMRasterFlags::RasterMode mode) = 0;
virtual QisMRasterFlags::RasterMode Get_raster_mode() const = 0;

QisMRasterParamsV2

Extension for QisMRasterParams (version = 2)

xxxxxxxxxx
class QisMRasterParamsV2: public QisMRasterParams { ... };

Set_overlay

Get_overlay

• Set/Get overlay mode.

• If on, the new image is drawn on top of the previous image (only if the image size in bytes is the same as the previous one).

• Otherwise, the image buffer is reset before the new image is rasterized.

• Default: off

xxxxxxxxxx
virtual void Set_overlay(const bool onoff) = 0;
virtual bool Get_overlay() const = 0;

QisMRasterParamsV3

Extension for QisMRasterParams (version = 3)

xxxxxxxxxx
class QisMRasterParamsV3: public QisMRasterParamsV2 { ... };

Set_bottom_to_top

Get_bottom_to_top

• Set/Get the rasterization direction.

• If true, rasterization occurs from bottom to top so that the minY of the data is found on the top row of the image.

• No change in the X direction.

• Default: false

xxxxxxxxxx
virtual void Set_bottom_to_top(const bool set) = 0;
virtual bool Get_bottom_to_top() const = 0;

QisMRasterParamsV4

Extension for QisMRasterParams (version = 4)

xxxxxxxxxx
class QisMRasterParamsV4: public QisMRasterParamsV3 { ... };

QisMRasterParamsV5

Extension for QisMRasterParams (version = 5)

xxxxxxxxxx
class QisMRasterParamsV5: public QisMRasterParamsV4 { ... };

Enum Code

• Represents parameter types to be used with Set_param and Get_param

• Determines the count and type(s) of arguments supplied to these methods to set/get the respective rasterization parameter

xxxxxxxxxx
enum Code 
{
  /* Enable/Disable native rasterization of PATH data
  * In Set_param, MUST be followed by ONE `int` with value 1 (ON) or 0 (OFF)
  * In Get_param, MUST be followed by ONE address of `int` to get the ON (1) or OFF (0) value
  * Default : 0 (OFF)
  * If OFF, all PATHs are converted to boundaries before being rasterized
  */
  RP_PATHS=1
  /* Enable/Disable native rasterization of circles/ellipses (only for paint&scratch format)
  * In Set_param, MUST be followed by ONE `int` with value 1 (ON) or 0 (OFF)
  * In Get_param, MUST be followed by ONE address of `int` to get the ON (1) or OFF (0) value
  * Default : 0 (OFF)
  * If OFF, all PATHs are converted to boundaries before being rasterized
  */
  ,RP_ELLIPSES
  /* Enable native rasterization of PATH data using a specific model. RP_PATHS must be 1 for this to take effect
  * When no model is specified or the specified model cannot be found, the default model is used
  * In Set_param, MUST be followed by ONE `const char*` which is the model name
  * In Get_param, MUST be followed by ONE address of `const char*` to get the model name
  * Default : 0 (OFF)
  * If OFF, all PATHs are converted to boundaries before being rasterized
  */
  ,RP_PATH_MODEL
};

Set_param

Get_param

• Set or Get value(s) for a particular rasterization parameter

• code represents the parameter in question

• ... is a variable list of arguments, the exact count and types of which depend on the parameter in question

• Returns true if the parameter was recognized and processed

xxxxxxxxxx
virtual bool Set_param(const int code, ...) = 0;
virtual bool Get_param(const int code, ...) const = 0;

QisMRasterPolygonSet

A data structure to store a set of polygons

xxxxxxxxxx
class QisMRasterPolygonSet { ... };

Reset (QisMRasterPolygonSet)

• Clear the polygon set

xxxxxxxxxx
virtual void Reset() = 0;

Version control (QisMRasterPolygonSet)

• Cast this pointer to any other version (base/derived)

• The version number is embedded in the class name in form of a suffix V<number>

• Get the latest version number supported by this implementation

xxxxxxxxxx
virtual const char* QisMRasterPolygonSet_name(const int version) const = 0;
virtual void* QisMRasterPolygonSet_cast(const int version) = 0;
virtual const void* QisMRasterPolygonSet_cast(const int version) const = 0;
virtual int QisMRasterPolygonSet_latest_version() const = 0;

Add_polygon

• Add a polygon to the set

• xy: An array of xy-coordinate pairs representing the closed polygon. It contains nv xy pairs or nv*2 integers. The co-ordinate values are in database units (DBU). 1 DBU = 1 file unit/grid e.g For a file with units as microns and grid of 1000/um (or 0.001 um), 1 DBU = 1000

• nv: Number of xy pairs. e.g A closed rectangle has nv == 5 (Last point is identical to the first)

• On success, returns true (the polygon is legal)

• The polygons are assumed to have the same grid and units as the QisMFile used to initialize the rasterizer

xxxxxxxxxx
virtual bool Add_polygon(const int* xy, const int nv) = 0;

Consolidate

• Use this to free up unused memory after all the polygons have been added

xxxxxxxxxx
virtual void Consolidate() = 0;

Count

• Get the number of polygons in the set

xxxxxxxxxx
virtual int Count() const = 0;

Data_extents

• Get the lower-left and upper-right co-ordinates of the extents of the data in this polygon set (in db units)

xxxxxxxxxx
virtual void Data_extents(
  double& llx, double& lly, double& urx, double& ury
  ) const = 0;

QisMRasterPolygonSetV2

Extension for QisMRasterPolygonSet (version = 2)

xxxxxxxxxx
class QisMRasterPolygonSetV2: public QisMRasterPolygonSet { ... };

Import_bstore

• Add polygons from QisMBStore. Will append to the polygons already added.

• Returns the number of polygons imported from the QisMBStore

xxxxxxxxxx
virtual int Import_bstore(const NsQisMLib::QisMBStore* polygons) = 0;

QisMRasterPolygonSetV3

Extension for QisMRasterPolygonSet (version = 3)

xxxxxxxxxx
class QisMRasterPolygonSetV3: public QisMRasterPolygonSetV2 { ... };

Iterator for QisMRasterPolygonSet

• Opaque pointer to a implementation specific iterator for traversing the polygon set

xxxxxxxxxx
typedef void* PolyIterator;

Count_v

• Get the sum of vertices for all polygons in the set

xxxxxxxxxx
virtual long long Count_v() const = 0;

Get_first

Get_next

End_iterator

• Iterate through the polygons in the set

• MUST start with Get_first followed by any number of Get_next

• Each call, returns --

  • A non-null iterator handle if there are more polygons to be traversed

  • NULL if all polygons have been traversed

• When NULL is returned, the iterator is automatically destroyed. No need to call End_iterator

• End_iterator should ONLY be used when one needs to terminate the iteration abruptly before reaching the end

xxxxxxxxxx
virtual QisMRasterPolygonSetV3::PolyIterator Get_first() const = 0;
virtual QisMRasterPolygonSetV3::PolyIterator Get_next(
  QisMRasterPolygonSetV3::PolyIterator itr
  ) const = 0;
virtual void End_iterator(
  QisMRasterPolygonSetV3::PolyIterator itr
  ) const = 0;

Num_xy_pairs

XY_pairs

• Get the number of vertices or array of x,y co-ordinates (in database units) for a specific polygon referenced by the specified iterator

xxxxxxxxxx
virtual int Num_xy_pairs(
  QisMRasterPolygonSetV3::PolyIterator itr
  ) const = 0;
virtual const int* XY_pairs(
  QisMRasterPolygonSetV3::PolyIterator itr
  ) const = 0;

QisMRasterPolygonSetV4

Extension for QisMRasterPolygonSet (version = 4)

xxxxxxxxxx
class QisMRasterPolygonSetV4: public QisMRasterPolygonSetV3 { ... };

Reset (QisMRasterPolygonSet)

• Remove all polygons from the set

xxxxxxxxxx
virtual void Reset() = 0;

Add_polygon

• Add a polygon (xy specified in db units) to the set

• Returns false if any of the paramters are invalid (xy is NULL or nv < 4)

xxxxxxxxxx
virtual bool Add_polygon(const int* xy, const int nv) = 0;

Add_frame

• Add a frame to the polygon set

• in_lx .. in_uy are the extents of the inner box in db units

• w_left .. w_top is the width of the frame along the respective sides in db units

• If not specified (<=0),

  • w_bottom and w_right are set to w_left

  • w_top is set to w_bottom

• Returns false if any of the parameters are invalid

xxxxxxxxxx
virtual bool Add_frame(
  const int in_lx, int in_ly, int in_ux, int in_uy,
  const int w_left, int w_bottom = 0, int w_right = 0, int w_top = 0
  ) = 0;

QisMRasterizer

Interface to an instance of the rasterizer

xxxxxxxxxx
class QisMRasterizer { ... };

Version control (QisMRasterizer)

• Cast this pointer to any other version (base/derived)

• The version number is embedded in the class name in form of a suffix V<number>

• Get the latest version number supported by this implementation

xxxxxxxxxx
virtual const char* QisMRasterizer_name(const int version) const = 0;
virtual void* QisMRasterizer_cast(const int version) = 0;
virtual const void* QisMRasterizer_cast(const int version) const = 0;
virtual int QisMRasterizer_latest_version() const = 0;

Get_last_error_msg (QisMRasterizer)

Get_last_error_code (QisMRasterizer)

• The information (error string and code) corresponding to the last error condition

xxxxxxxxxx
virtual const char* Get_last_error_msg() const = 0;
virtual int Get_last_error_code() const = 0;

Rasterize_window

• Rasterize a single window using polygons belonging to one or more layers for a given cell

• name: Name associated with this raster image. It will be used as the base path (directory + filename) if this image is written to disk as TIFF/BMP/RAW

• llx, lly, urx, ury: Lower-left and upper-right co-ordinates of the window to be rasterized (in file units)

• params: Rasterization options

• viewCell: Name of the cell to be rasterized. If NULL/empty, the deepest top cell in the file is used

• layers: A string containing comma-separated list of layers or layer:datatypes to be rasterized. If NULL/empty, all layers will be used

• Success: A non-NULL handle to the raster image

• Failure: NULL. Call Get_last_error_msg() for more information about the error

• For multiple windows, use this method in a loop. The image buffer will be automatically adjusted to match the image/window size

xxxxxxxxxx
virtual const QisMRasterImage* Rasterize_window(
  const char* name,
  const double llx, const double lly, const double urx, const double ury,
  const QisMRasterParams* params, const char* viewCell, const char* layers
  ) = 0;

Rasterize_window_synthesized

• Rasterize a single window using polygons created by performing various boolean operation on layers for a given cell

• name: Name associated with this raster image. It will be used as the base path (directory + filename) if this image is written to disk as TIFF/BMP/RAW

• llx, lly, urx, ury: Lower-left and upper-right co-ordinates of the window to be rasterized (in file units)

• params: Rasterization options

• viewCell: Name of the cell to be rasterized. If NULL/empty, the deepest top cell in the file is used

• synthSpec: Specification of boolean operations between layers. All target layers will be rasterized

• Success: A non-NULL handle to the raster image

• Failure: NULL. Call Get_last_error_msg() for more information about the error

• For multiple windows, use this method in a loop. The image buffer will be automatically adjusted to match the image/window size

xxxxxxxxxx
virtual const QisMRasterImage* Rasterize_window_synthesized(
  const char* name,
  const double llx, const double lly, const double urx, const double ury,
  const QisMRasterParams* params, const char* viewCell, const char* synthSpec
  ) = 0;

Rasterize_polygon_set

• Rasterize a pre-computed set of polygons specific to the client application

• name: Name associated with this raster image. It will be used as the base path (directory + filename) if this image is written to disk as TIFF/BMP/RAW

• polygonSet: Pre-computed set of polygons to be rasterized

• params: Rasterization options

• rasterWindow: If not NULL, specify a window into the polygon set to be rasterized. If NULL, the overall extents of the polygon set will be used as the raster window

• offsets, nOffsets: If not NULL/empty, specify a set of xy-coordinates at which the specified set of polygons repeat (as a whole). In this case, the polygon set is used as a pattern that repeats at one or more places. The reference origin of this pattern is assumed to be 0,0. If NULL/empty, the specified polygon set is rasterized as-is at their specified co-ordinates

• Success: A non-NULL handle to the raster image

• Failure: NULL. Call Get_last_error_msg() for more information about the error

• For multiple windows, use this method in a loop. The image buffer will be automatically adjusted to match the image/window size

xxxxxxxxxx
virtual const QisMRasterImage* Rasterize_polygon_set(
  const char* name, const QisMRasterPolygonSet* polygonSet, 
  const QisMRasterParams* params, const double* rasterWindow = 0,
  const double* offsets = 0, const int nOffsets = 0
  ) = 0;

QisMRasterizerV2

Extension for QisMRasterizer (version = 2)

xxxxxxxxxx
class QisMRasterizerV2: public QisMRasterizer { ... };

Preset_raster_view

• Set the view cell/layers before rasterization if a it's not going to change for many windows to come

• viewCell: Name of the cell to be rasterized. If NULL/empty, the deepest top cell in the file is used

• layers: A string containing comma-separated list of layers or layer:datatypes to be rasterized. If NULL/empty, all layers will be used

• Success: A non-NULL handle to the raster image

• Failure: NULL. Call Get_last_error_msg() for more information about the error

xxxxxxxxxx
virtual bool Preset_raster_view(
  const char* viewCell = 0, const char* layers = "ALL"
  ) = 0;

Rasterize_window_preset_view

• Rasterize a window (assuming that the view cell/layers have already been set)

• name: Name associated with this raster image. It will be used as the base path (directory + filename) if this image is written to disk as TIFF/BMP/RAW

• llx, lly, urx, ury: Lower-left and upper-right co-ordinates of the window to be rasterized (in file units)

• params: Rasterization options

• Success: A non-NULL handle to the raster image

• Failure: NULL. Call Get_last_error_msg() for more information about the error

• For multiple windows, use this method in a loop. The image buffer will be automatically adjusted to match the image/window size

• If the cell was not set using Preset_raster_view, the default top cell will be used. If the layers were not set, ALL layers will be used. Otherwise the pre-set cell, layers will be used

xxxxxxxxxx
virtual const QisMRasterImage* Rasterize_window_preset_view(
  const char* name,
  const double llx, const double lly, const double urx, const double ury,
  const QisMRasterParams* params
  ) = 0;

Overlay_polygon_set

• Overlay the existing raster buffer with a set of polygons

• original_image : The image to be used as a base for the overlay. The image MUST be generated using the same rasterizer object

• polygonSet: Set of polygons to be overlayed

• mode: Paint mode - dither, paint or scratch (One of QisMRasterFlags::OverlayMode)

• offsets, nOffsets: If not NULL/empty, specify a set of xy-coordinates at which the specified set of polygons repeat (as a whole). In this case, the polygon set is used as a pattern that repeats at one or more places.

• The reference origin of this pattern is assumed to be 0,0. If NULL/empty, the specified polygon set is rasterized as-is at their specified co-ordinates

• Success: A non-NULL handle to the raster image

• Failure: NULL. Call Get_last_error_msg() for more information about the error

• Use this method to overlay a set of polygons on the existing raster image buffer

• This method MUST only be used AFTER an initial image is generated using Rasterize_window, Rasterize_window_synthesized, Rasterize_polygon_set or Rasterize_window_preset_view using the SAME rasterizer

• The raster settings applied for the overlay (threads, inversion, etc.) are same as the original raster job

• This method can be used multiple times in succession once the original image is created

• Only the data that crosses the original window extents will appear as overlay

xxxxxxxxxx
virtual const QisMRasterImage* Overlay_polygon_set(
  const QisMRasterImage* original_image, const QisMRasterPolygonSet* polygonSet, 
  const QisMRasterFlags::OverlayMode mode = QisMRasterFlags::OMF_DITHER,
  const double* offsets = 0, const int nOffsets = 0
  ) = 0;

QisMRasterizerV3

Extension for QisMRasterizer (version = 3)

xxxxxxxxxx
class QisMRasterizerV3: public QisMRasterizerV2 { ... };

Rasterize_window_paint_scratch

• Same as QisMRasterizerV4::Rasterize_window_paint_scratch_v2 with spec and layers set to NULL

xxxxxxxxxx
virtual const QisMRasterImage* Rasterize_window_paint_scratch(
  const char* name,
  const double llx, const double lly, const double urx, const double ury,
  const QisMRasterParams* params, const char* viewCell, const char* spec
  ) = 0;

QisMRasterPSInfo_p

Opaque handle that represents an instance of the paint & scratch (v2) spec.

xxxxxxxxxx
typedef void* QisMRasterPSInfo_p;

QisMRasterizerV4

Extension for QisMRasterizer (version = 4)

xxxxxxxxxx
class QisMRasterizerV4: public QisMRasterizerV3 { ... };

Rasterize_px_window

• Rasterize a window whose co-ordinates are specified in pixel space.

• px_llx .. px_ury are the co-ordinates of the window in pixel space

• width_bytes is the image width in bytes

• height_px is the image height in pixels (or bytes)

• params is a valid handle to the rasterization paramters

• cell (if not empty) is the view cell name

• layers (if not empty) is a comma-separated list of layers to be rasterized

• On success, returns a non-null handle to an image. Otherwise call Get_last_error_msg for error information

• pixel_coordinate = round(file_coordinate/pixelsize)

xxxxxxxxxx
virtual const QisMRasterImage* Rasterize_px_window(
  const char* name,
  const int px_llx, const int px_lly, const int width_bytes, 
  const int height_px, const QisMRasterParams* params, 
  const char* cell, const char* layers
  ) = 0;

Create_paint_scratch_v2_spec

Destroy_paint_scratch_v2_spec

• Create a paint & scratch specification (v2-cell based) for rasterizing paint & scratch data from a cell-based paint and scratch database

• view_cell is the cell to be rasterized

• pxsize_x, pxsize_y is the resolution in pixel-size (file units)

• roi if specified is the window if interest

• On success, returns a handle to the specification object. Otherwise, call Get_last_error_msg for error details

• Every spec. created this way MUST be eventually destroyed using Destroy_paint_scratch_v2_spec to avoid memory leaks

xxxxxxxxxx
virtual QisMRasterPSInfo_p Create_paint_scratch_v2_spec(
  const char* view_cell, const double pxsize_x, const double pxsize_y,
  const NsQisMLib::QisMWindow* roi = 0
  ) = 0;
virtual void Destroy_paint_scratch_v2_spec(QisMRasterPSInfo_p handle) = 0;

Rasterize_window_paint_scratch_v2

• Rasterize a window of a paint and scratch (v2-cell based) database

• name is the name associated with this raster image. It will be used as the base path (directory + filename) if this image is written to disk as TIFF/BMP/RAW

• llx, lly, urx, ury are the lower-left and upper-right co-ordinates of the window to be rasterized (in file units)

• params Rasterization options

• viewCell is the name of the cell to be rasterized. If NULL/empty, the deepest top cell in the file is used

• spec is the paint & scratch spec. If not specified (null), this method computes the spec. itself

• layers if specified (!=NULL and !=""), represents the layers to rasterize

• On success, returns a non-null handle to the image

• Failure: NULL. Call Get_last_error_msg() for more information about the error

• For multiple windows, use this method in a loop. The image buffer will be automatically adjusted to match the image/window size

xxxxxxxxxx
virtual const QisMRasterImage* Rasterize_window_paint_scratch_v2(
  const char* name,
  const double llx, const double lly, const double urx, const double ury,
  const QisMRasterParams* params, const char* viewCell, 
  const QisMRasterPSInfo_p spec, const char* layers = 0
  ) = 0;

QisMRasterizerV5

Extension for QisMRasterizer (version = 5)

xxxxxxxxxx
class QisMRasterizerV5: public QisMRasterizerV4 { ... };

Create_grayscale

Destroy_grayscale

• Convert a 1bpp monochome raster image to a gray scale image with choice of sampling rate and bits-per-px

• img is a handle to a valid 1bpp raster image obtained via any of the QisMRaster operations

• mode represents one of the supported gray scale modes. See QisMRasterFlags::Grayscale_modes

• thrnum is the no. threads to be used for this operation

• On success, returns a non-NULL handle to the newly created gray scale image in a separate memory buffer

• Every gray scale image MUST be eventually destroyed by Destroy_grayscale to avoid resource leaks

xxxxxxxxxx
virtual QisMGrayscaleImage* Create_grayscale(
  const QisMRasterImage* img, const int mode, const int thrnum
  ) = 0;
virtual void Destroy_grayscale(QisMGrayscaleImage* img) = 0;

Destroy_grayscale_buffer

• Destroy the image buffer that was de-coupled from the image object. See Detach_buffer

xxxxxxxxxx
virtual void Destroy_grayscale_buffer(unsigned char* buffer) = 0;

QisMRasterizerV6

Extension #6 to QisMRasterizer (version = 6)

xxxxxxxxxx
class QisMRasterizerV6: public QisMRasterizerV5 { ... };

Subsample_2x2

Destroy_subsampler

• Downsize a raster image (halve the resolution on each side) using a recipe

• name is the name of the new raster image

• in is the handle to the source raster image to be downsized

• recipe is used to control how a sample of 2x2 pixels is set/reset in the output buffer. See sub-sampling for details

• recipe_sz is the size of this array (MUST be 16)

• option followed by ... is a set of optional parameters. each parameter consists of an opt-code followed by the value for that parameter. the opt-code is one of QisMRasterSubSampler::Options. the type of the value depends on the opt-code. this set of parameters MUST end with a 0 or QisMRasterSubSampler::SSO_END

• Returns a handle to the sub-sampled image object on success. Otherwise, call Get_error_msg for error information

• This object MUST be eventually destroyed using Destroy_subsampler to avoid resource leaks

xxxxxxxxxx
virtual QisMRasterSubSampler* Subsample_2x2(
  const char* name, const QisMRasterImage* in, const unsigned char* recipe,
  const int recipe_sz, const int option, ...
  ) = 0;
virtual void Destroy_subsampler(QisMRasterSubSampler* handle) = 0;

Destroy_subsampled_buffer

• Destroy the buffer detached from the subsampled image object

xxxxxxxxxx
virtual void Destroy_subsampled_buffer(unsigned char* buffer) = 0;

QisMRasterizerV7

Extension #7 to QisMRasterizer (version = 7)

xxxxxxxxxx
class QisMRasterizerV7: public QisMRasterizerV6 { ... };

New_image

• Start a new raster image

• Previous image buffer will either be re-used or destroyed

• name is to be associated with this new image

• params specify the rasterization options

• extents represent the window in data space to be rasterized

• Returns a handle to the fresh clean image ready for rasteriztion

• On error, returns NULL. Use Get_last_error_msg to get more information

xxxxxxxxxx
virtual QisMRasterImage* New_image(
  const char* name, const QisMRasterParams* params, 
  const NsQisMLib::QisMWindow& extents
  ) = 0;

Overlay_polygon

• Overlay one polygon represented by xy (user units) and nv to the existing image

• mode determined how this polygon is rasterized

• offsets and nOffsets represents repetition if not NULL and 0 respectively

• If the polygon crosses the image extents, it will be clipped or dropped accordingly

• Returns a handle to the fresh clean image ready for rasteriztion

• On error, returns NULL. Use Get_last_error_msg to get more information

xxxxxxxxxx
virtual const QisMRasterImage* Overlay_polygon(
  const QisMRasterImage* original_image,
  const double* xy, const int nv, const QisMRasterFlags::OverlayMode mode,
  const double* offsets, const int nOffsets
  ) = 0;

Overlay_polygon_dbu

• Overlay one polygon represented by xy (db units) and nv to the existing image

• original_image is a handle to an existing image object

• mode determines how this polygon is rasterized

• offsets and nOffsets represents repetition if not NULL and 0 respectively

• If the polygon crosses the image extents, it will be clipped or dropped accordingly

• Returns a handle to the fresh clean image ready for rasteriztion

• On error, returns NULL. Use Get_last_error_msg to get more information

xxxxxxxxxx
virtual const QisMRasterImage* Overlay_polygon_dbu(
  const QisMRasterImage* original_image,
  const int* xy_dbu, const int nv, const QisMRasterFlags::OverlayMode mode,
  const int* offsets_dbu, const int nOffsets
  ) = 0;

Overlay_box_dbu

• Overlay one box specified in DBU to an existing image

• original_image is a handle to an existing image object

• lx..uy are the box extents in DBU

• mode determines how this polygon is rasterized

• If the polygon crosses the image extents, it will be clipped or dropped accordingly

• Returns a handle to the fresh clean image ready for rasteriztion

• On error, returns NULL. Use Get_last_error_msg to get more information

xxxxxxxxxx
virtual const QisMRasterImage* Overlay_box_dbu(
  const QisMRasterImage* original_image,
  const int lx, const int ly, const int ux, const int uy, 
  const QisMRasterFlags::OverlayMode mode
  ) = 0;

Set_limit_extents

• In solutions where multiple rasterizers work together on a shared buffer, limit the extents of this rasterizer to the tile/window assigned to it

• This is necessary to both reduce the amount of redundant rasterization as well as avoid simultaneous access to parts of the buffer

• Not required when each rasterizer has it's own image object (i.e the rasterizer was created without the use of a shared buffer)

• exts are the window extents in user units

xxxxxxxxxx
virtual void Set_limit_extents(const NsQisMLib::QisMWindow& exts) = 0;

QisMRasterizerV8

Extension #8 to QisMRasterizer (version = 8)

xxxxxxxxxx
class QisMRasterizerV8: public QisMRasterizerV7 { ... };

Overlay_ellipse

• Overlay an ellipse in the current image buffer (original_image) which MUST be valid

• xc, yc is the center of the ellipse in file (user) units

• rx, ry are the radii along X and Y respectively also in file (user) units (has to be both > 0.0)

• mode determines how the ellipse is rasterized

• offsets and nOffsets represents repetition (in file units) if not NULL and 0 respectively

• On success, returns a pointer to the same image object. On error, returns NULL. Use Get_last_error_msg to get error information

xxxxxxxxxx
virtual const QisMRasterImage* Overlay_ellipse(
  const QisMRasterImage* original_image,
  const double xc, const double yc, const double rx, const double ry,
  const QisMRasterFlags::OverlayMode mode,
  const double* offsets = 0, const int nOffsets = 0
  ) = 0;

Overlay_path

• Overlay an path in the current image buffer (original_image) which MUST be valid

• width is the path width in file (user) units

• round_cap is true if the path has round caps (both start and end)

• start_x, end_x is the amount of extension (in file units) to be added at the start and end respectively. Positive values elongate the path in either directions. Negative values shrink the path

• mode determines how the path is rasterized

• offsets and nOffsets represents repetition (in file units) if not NULL and 0 respectively

• On success, returns a pointer to the same image object. On error, returns NULL. Use Get_last_error_msg to get error information

xxxxxxxxxx
virtual const QisMRasterImage* Overlay_path(
  const QisMRasterImage* original_image, const double* xy, const int nv,
  const double width, const bool round_cap, const double start_x, const double end_x, 
  const QisMRasterFlags::OverlayMode mode,
  const double* offsets = 0, const int nOffsets = 0
  ) = 0;

QisMRasterizerV9

Extension #9 to QisMRasterizer (version = 9)

xxxxxxxxxx
class QisMRasterizerV9: public QisMRasterizerV8 { ... };

Set_refresh_notify

• Set the handler that will receive the refresh notification

• NULL implies no such handler/no need for refresh notifications (which is also the default setting)

xxxxxxxxxx
virtual void Set_refresh_notify(QisMRasterNotifyV3* handler) = 0;

QisMRasterizerV10

Extension #10 to QisMRasterizer (version = 10)

xxxxxxxxxx
class QisMRasterizerV10: public QisMRasterizerV9 { ... };

Overlay_box_dbu_offx

• Overlay a box with repetitions in the the current buffer represented by original_image

• lx..uy are the extents of the first box

• mode determines how the boxes are rasterized

• offsets_dbu and nOffsets represents repetition (in dbu) if not NULL and 0 respectively

• On success, returns a pointer to the same image object. On error, returns NULL. Use Get_last_error_msg to get error information

xxxxxxxxxx
virtual const QisMRasterImage* Overlay_box_dbu_offx(
  const QisMRasterImage* original_image,
  const int lx, const int ly, const int ux, const int uy,
  const QisMRasterFlags::OverlayMode mode, const int* offsets_dbu,
  const int noffsets
  ) = 0;

Overlay_ellipse_dbu

• Overlay an ellipse (in dbu) in the the current buffer represented by original_image

• xc_dbu and yc_dbu are the co-ordinates of the center point

• rx_dbu and ry_dbu are the radii along X and Y

• mode determines how the boxes are rasterized

• offsets_dbu and nOffsets represents repetition (in dbu) if not NULL and 0 respectively

• On success, returns a pointer to the same image object. On error, returns NULL. Use Get_last_error_msg to get error information

xxxxxxxxxx
virtual const QisMRasterImage* Overlay_ellipse_dbu(
  const QisMRasterImage* original_image,
  const int xc_dbu, const int yc_dbu, const int rx_dbu, const int ry_dbu,
  const QisMRasterFlags::OverlayMode mode,
  const int* offsets_dbu, const int nOffsets
  ) = 0;

QisMRasterizerV11

Extension #11 to QisMRasterizer (version = 11)

xxxxxxxxxx
class QisMRasterizerV11: public QisMRasterizerV10 { ... };

Overlay_ring

• Overlay a ring in the the current buffer represented by original_image

• cx and cy are the co-ordinates of the center point

• radius is the radius (>0.0) and width is the thickness (>0.0)

• mode determines how the ring is rasterized

• arcres and arcsag if specified are the arc resolution (degrees) and chord error (in user-units) to control the smoothness of the circle

• offsets and nOffsets represents repetition if not NULL and 0 respectively

• All values are in user-units

• On success, returns a pointer to the same image object. On error, returns NULL. Use Get_last_error_msg to get error information

xxxxxxxxxx
virtual const QisMRasterImage* Overlay_ring(
  const QisMRasterImage* original_img, const double cx, const double cy,
  const double radius, const double width, const QisMRasterFlags::OverlayMode mode,
  const double arcres = 9.0, const double arcsag = 0.0,
  const double* offsets = 0, const int nOffsets = 0
  ) = 0;

DPI_to_pixelsize

Pixelsize_to_DPI

• Convenience methods to convert DPI (dots-per-inch) to size-of-a-pixel (user-units) and visa-versa

xxxxxxxxxx
virtual double DPI_to_pixelsize(const double dpi) const = 0;
virtual double Pixelsize_to_DPI(const double pxs) const = 0;

File_db

• Returns a handle to the file database associated with this object

xxxxxxxxxx
virtual NsQisMLib::QisMFile* File_db() = 0;
virtual const NsQisMLib::QisMFile* File_db() const = 0;

QisMFormatter

Interface to an instance of the image formatter

xxxxxxxxxx
class QisMFormatter { ... };

Version control (QisMFormatter)

• Cast this pointer to any other version (base/derived)

• The version number is embedded in the class name in form of a suffix V<number>

• Get the latest version number supported by this implementation

xxxxxxxxxx
virtual const char* QisMFormatter_name(const int version) const = 0;
virtual void* QisMFormatter_cast(const int version) = 0;
virtual const void* QisMFormatter_cast(const int version) const = 0;
virtual int QisMFormatter_latest_version() const = 0;

Get_last_error_msg (QisMFormatter)

Get_last_error_code (QisMFormatter)

• The information (error string and code) corresponding to the last error condition

xxxxxxxxxx
virtual const char* Get_last_error_msg() const = 0;
virtual int Get_last_error_code() const = 0;

Write_tiff

• Write a raster image to a TIFF file with packbits compression

• filePath: Path of the file to be created

• pxWidth: Width of the image in pixels

• imgSizeBytes: Size of the image in bytes

• dpiX, dpiY: Image resolution in dots-per-inch

• buffer: Address of the memory buffer where the image is held

• numThreads: No. threads to be used for formatting the image

• Success: true

• Failure: false. Call Get_last_error_msg() for details