exportImage Method

Description

Exports the current drawing as an image. The resulting image is passed into the onSuccess function as a Base64 encoded string.

Syntax

.exportImage(/* Object */ options, /* Function */ onSuccess, /* Function */ onError)

Parameters

options: Object

A hash of values that control the image export operation. The valid values are:

ignoreMapError — When true, errors that occur while updating the map in the diagram will be ignored. When a map update error occurs and this option is enabled, the exported diagram image will not include the map.
The default is false.

format — Specifies the image format. 'image/jpeg' (JPEG) and 'image/png' (PNG) are supported.
If not specified the exportOptions property in userSettings will be used.

imageQuality — This value sets the quality level for a JPEG export. Acceptable values are between 0.0 and 1.0. For best quality specify 1.0. A quality setting of 0.75 provides good image quality and compression. Lower quality settings provide greater image compression. This value is ignored when exporting a PNG image.
If not specified the exportOptions property in userSettings will be used.

trim — This option, when set to true, trims the white space so the resulting image has the same aspect ratio as the diagram's viewbox.
The default is false.

resolutionPixels - The number of pixels per output resolution unit. This value and the value of resolutionUnit define the output resolution. Output resolution is always resolutionPixels / 1 resolutionUnit. For example, if resolutionUnit is 'inch' and resolutionPixels is 300, the output resolution will be 300px/inch.
If not specified the exportOptions property in userSettings will be used.

Note: Output resolution is important for two reasons. First, it used to convert output sizes (width, height, margin) expressed as linear measurements to pixels. Second, some diagram features are sized based on output resolution. Items on the measurement layer and structure dimension lines are examples of this behavior. The sizes of these items are defined in points (1/72") and the output resolution is used to calculate their output size in pixels.

resolutionUnit — A standard linear unit of measure like 'inch' or 'cm' that is combined with resolutionPixels to define output resolution.
If not specified the exportOptions property in userSettings will be used.

width — The image width in pixels or expressed as a linear measurement like '7.5"' or '20cm'. When width is expressed as a linear measurement it will be converted to pixels based on the output resolution. For example if width is '7.5"' and output resolution is 300px/inch, the resulting width will be 2250px.
If not specified the exportOptions property in userSettings will be used.

height — The image height in pixels or expressed as a linear measurement like '10"' or '5cm'. When height is expressed as a linear measurement it will be converted to pixels based on the output resolution. For example if height is '10"' and output resolution is 300px/inch, the resulting height will be 3000px.
If not specified the exportOptions property in userSettings will be used.

margin — The image margin width in pixels or expressed as a linear measurement like '0.25"' or '0.5cm'. When margin is expressed as a linear measurement it will be converted to pixels based on the output resolution. For example if margin is '0.5"' and output resolution is 300px/inch, the resulting margin will be 75px.
If not specified the exportOptions property in userSettings will be used.

includePrefix — When set to true, adds a data: URL prefix to the exported image string. This image can then be used directly in the browser. See Example 2 below for details.
The default value is true.

Note: Although the exported image may be used in this manner, keep in mind that the SVG returned from the store method can be easily displayed in your page. Using the SVG is more efficient than exporting the image and provides greater fidelity.

includeStructureDimensions — When set to true, wall length dimension lines will be included in the exported image, if the diagram contains one or more structure shapes.
If not specified the value derived from userSettings will be used.

includeFieldMeasurements — When set to true, shapes from the measurement layer will be included in the generated image.
If not specified the value derived from userSettings will be used.

includeAttachments — When set to true, attachments will be visible in the exported image.
If not specified the value derived from userSettings will be used.

viewKey — The key of the view to be output as an image.
The default is 0 which is the key of the main diagram.

onSuccess: Function

This function will be called when diagram export completes successfully. It will be passed two parameters:

  1. A base 64 encoded image of the diagram as specified in options.
  2. A hash of information related to the diagram and exported image as specified in the options parameter. The items in this hash may include:
    • fieldMeasurements: an object containing the measurement layer data.

      Here is an example of the measurement layer data: 
      {
  units: "feetAndInches",
  stationLines: [
	{
	  stationLineIncrement: 0,
	  formattedStationLineIncrement: "0'",
	  markers: [
		{
		  id: "1",
		  description: "Station Line One",
		  station: 10,
		  formattedStation: "10'",
		  distance: 10,
		  formattedDistance: "10'",
		  direction: "R"
		}
	  ]
	}
  ],
  triangulationMeasurements: {
	markerPoints: [
	  {
		id: "1",
		description: "Measurement Point One",
		refPt1: "A",
		refPt2: "B",
		distance1: 20,
		formattedDistance1: "20'",
		distance2: 20,
		formattedDistance2: "20'",
		direction: "L"
	  }
	]
  }
}
      Note: the measurement layer data includes formatted and numeric versions of length and distance values.

onError: Function

A function that accepts one parameter, a JavaScript Error object. This function will be called if the export fails. An Error object indicating the nature of the failure will be passed to it. If this function does not return true, indicating that the error has been handled, the error will be passed on to the built-in error handler.

Example 1 — Export a PNG Image

/*
    This example assumes esdEditor is an initialized
    ESDWeb object and that a diagram is loaded
*/

function onExport (image) {
	// The export was successful...
	// The parameter "image" contains a 500 x 500 base 64
	// encoded PNG image of the diagram.
	// Any operations that depend on the exported image must
	// be done within the body of this callback function.
}

function onError (error) {
	alert('Export failed: ' + error.message);
}

// Export the diagram as a png image.
esdEditor.exportImage({
	format: 'image/png',
	margin: 10,
	width: 500,
	height: 500
}, onExport, onError);

Example 2 — Export and Display a JPG Image

/*
	This example assumes esdEditor is an initialized
	ESDWeb object and that a diagram is loaded
*/

function onExport (image) {
	// 'esdImage' is the id of an existing <img> element in the DOM.
	var img = document.getElementById('esdImage');

	// Set the image to be shown by the element.
	img.src = image;
}

function onError (error) {
	alert('Export failed: ' + error.message);
}

// Export the diagram as a jpeg image, ignoring map update errors.
esdEditor.exportImage({
	format: 'image/jpeg',
	imageQuality: 0.9,
	margin: 10,
	width: 600,
	height: 400,
	includePrefix: true
}, onExport, onError);