Surveyor Workspace Format (.sws)


Surveyor by default generates scanned images in the Surveyor Workspace (.sws) format. This is a tiled image format comprising of:

  • a folder on disk with the individual high resolution image tiles of the scan,
  • low resolution thumbnail images, which are either individual .thb files or single .bin file,
  • some metadata files e.g. tile position information,
  • a single .sws file.

The Surveyor Workspace format is not restricted in size and the limitations of the scan are effectively a consequence of the hardware capabilities of the scanning machine.

The Surveyor Workspace format can be loaded in either the Surveyor application or the individual viewer application OIViewer which is available on the Objective Imaging website.

Additionally it is possible to parse the Surveyor Workspace format programmatically and this is done using the Workspace Reader DLL for Windows systems.

See the downloads page of the website for both of these items: http://www.objectiveimaging.com/download/software.php

Export Mosaic Formats

Surveyor also allows the export of scanned mosaics in other common formats:
  • Bitmap (.bmp)
  • Tiff (.tif)
  • BigTiff (.tif)
  • Jpeg (.jpg/.jpeg)

Each format has it's own restrictions, some of which are outlined below.

Bitmap Format (.bmp)

Bitmap images larger than 30,000 pixels width or height are not supported across many applications. This includes Adobe Photoshop and Windows Photo Viewer for example. These programs will often popup an error stating that the image is corrupted. IrfanView and ImageJ are known to be able to load 30,000 pixel width/height bitmap images.

It is easy to exceed 30,000 pixels in Surveyor when scanning an area of the stage which isn't so large with a 20X lens, for example. Some more information from Adobe is available here: https://helpx.adobe.com/photoshop/using/saving-images.html#WSfd1234e1c4b69f30ea53e41001031ab64-777ca

4GB is the maximum theoretical file size of a bitmap file according to the specifications of this format. Surveyor continues to write image data beyond the 4GB limit, thus allowing third-parties to access the full scanned image if they wish to implement custom file handling.

A 64-bit image viewer is typically needed to load such large images. 32-bit applications have only ~2GB usable memory address space allocated to the process on a Windows operating system. This means both the application resources and image data must fit into 2GB of memory. Photoshop uses "scratch disks" to swap data in and out of memory using the hard disk as a buffer, for example, which allows it to run a bit better with a bit less. Surveyor uses the Surveyor Workspace (.sws) format which swaps between reduced resolution thumbnail images and the high resolution images to lower memory requirements, and this is very effective in allowing large scans on a 32-bit application.

Finding an application to read large bitmap images is not straightforward. 64-bit Photoshop still has a 30,000 pixel limitation (at last check) and IrfanView is 32-bit only. ImageJ can run in 64-bit Java however our most recent tests have shown this to still have problems.

Ultimately these images should not be expected to be easily viewed and we would advise the following:
  • Test your capability to load large bitmap images in your applications.
  • Consider exporting a region of interest (ROI) rather than the full image, which will allow a smaller file size.
  • Consider scaling the image during export for the same reason.

Tiff Format (.tif/.tiff)
Traditional tiff specification has a maximum file size of 4GB. Surveyor uses the third-party LibTiff implementation to generate tiff files. These are scanlined based (ie. not tiled). It may be easier to view up to 4GB images in tiff format than bitmap format in most image applications.

BigTiff Format (.tif/.tiff)

This is an extension of the traditional tiff format which is designed to allow greater than 4GB file size. This would be the recommended output format for very large mosaic images where the Surveyor Workspace (.sws) format is not desired. For most scans the BigTiff output is tile-based, although under some circumstances Surveyor will generate a scanline based output. Aperio have a viewer program capable of loading these images, other such programs may also be available.

Jpeg Image Format (.jpg/.jpeg)

Surveyor currently supports a jpeg implementation which is restricted to buffer size of 2GB prior to compression. Jpeg is a lossy format which means the quality of the image is compressed and image detail is lost at the expense of file size.