Name: export with palette

Type: command

Syntax: export <image> [with metadata <metadata>] to {file <filePath> | <container>} as {gif | png} with standard palette

Syntax: export <image> [with metadata <metadata>] to {file <filePath> | <container>} as {gif | png} with optimized palette

Syntax: export <image> [with metadata <metadata>] to {file <filePath> | <container>} as {gif | png} with <colorCount> color [optimized] palette

Syntax: export <image> [with metadata <metadata>] to {file <filePath> | <container>} as {gif | png} with palette <colorList>

Summary:
<export|Exports> the <selected> <image> as a <PBM>, <JPEG>, <GIF>, <BMP>
or <PNG> <file>.

Introduced: 4.5

OS: mac, windows, linux

Platforms: desktop

Security: disk

Example:
export image 1 to myVariable as png with standard palette

Example:
export image "Parachute" to myVariable as gif with 100 color palette

Parameters:
image:
A reference to an <image>.

metadata (array):
An array of metadata. Currently the only key supported is density with a
value in pixels per inch (ppi).


filePath:
The <file path|name and location> of the <file> you want to <export> to.
If you specify a name but not a location, the <file> is created in the
<defaultFolder>. 

container:
A reference to a <container>, usually another <image> or a <URL>.

colorCount (integer):
An integer in the range zero to 256, or an expression evaluating to such
an integer, and specifies the size of the palette to be generated.

colorList:
A return-delimited list of up to 256 colors to be used as the palette.

Description:
Use the <export with palette> <command> to <export> an <image> to a
<file> or <container> with color reduction.

The export with palette form exports an image in either PNG or GIF
format with a specific size or type of palette.

If the standard palette form is used, then the image will be
color-matched to the default 256 color LiveCode palette before export.

If the optimized palette form is used, then a palette with the
<colorCount> colors will be generated that does its best to approximate
all the colors present in the image. The image will be color-matched to
this palette before export. If colorList is not specified, a 256 entry
palette will be generated.

If the palette colorList form is used, the image will be color-matched
to that palette before export.

If the image has any sort of transparency, then this will utilize one
palette entry. In particular, if you ask for a 256 color palette with a
transparent image, you may get only 255 colors.

In all cases, optional dithering will be performed as determined by its
dontDither property.

>*Note:* It is a (relatively) slow process to compute an optimized
> palette and then remap an image against it; it should not be
> considered a real-time operation except for very small images.

>*Note:* There is no support for exporting a JPEG with a reduce palette
> as this format is for continuous-tone images and as such the notion of
> palette makes no sense.

References: export (command), export snapshot (command), import (command),
BMP (glossary), command (glossary), container (glossary), export (glossary), 
GIF (glossary), JPEG (glossary), PBM (glossary), PNG (glossary), 
as (keyword), file (keyword), image (keyword), paint (keyword), URL (keyword),
defaultFolder (property), JPEGQuality (property), selected (property)
