JpegImage Object
Overview
JpegImage represents an image and encapsulates most of the component's functionality. This object is created by calling JpegManager's OpenImage or CreateImage methods.
Member List
Properties
Returns true if the current image has an alpha channel associated with it (e.g. if a PNG file with an alpha channel was opened.) The alpha channel, if present, only has effect when the image is saved in PNG format (the PNGOutput property is set to true.)
See also: Chapter 10 - PNG Output.
Sets or retrieves the alpha value of a pixel specified via 0-based (X, Y) coordinates. This property can only be used if the current image has an alpha channel associated with it, which can be determined using the AlphaExists property. This property returns, or is assigned, an integer value in the range 0 to 255. The X and Y coordinates must be in the range (0, Width - 1) and (0, Height - 1), respectively.
See also: Section 10.3 - Alpha Channel Management.
Returns an array of bytes representing the thumbnail. This property is useful for saving thumbnails in the database as BLOBs. Can be used instead of Save/SendBinary if the ultimate destination of the thumbnail is a database table.
See also: Section 2.4 - Output to Memory.
Returns the JpegCanvas object which, along with its sub-objects JpegFont, JpegPen, JpegBrush and JpegUV enables writing and drawing over an image.
See also: Chapter 5 - Drawing & Typing.
Returns the number of color components per pixel. An RGB image has 3 components, CMYK image - 4, and grayscale image - 1. This property may return a different value than OriginalComponents in case the image has been converted to another color space by calling ToRGB or ToGrayscale.
Specifies a new image height (in pixels).
Side effect: if PreserveAspectRatio is set to true, changing this property automatically changes Width to preserve the original aspect ratio of the image.
See also: Section 2.1 - Thumbnail-Creating Steps.
Specifies an image resizing algorithm. The values from 0 to 15 are currently supported. The most commonly used values are: 0 (Nearest-Neighbor), 1 (Bilinear, default) and 2 (Bicubic).
The Nearest-Neighbor (NN) is the fastest but provides low-quality thumbnails.
The Bilinear method offers much better thumbnail quality but is approximately 2 times as slow as NN.
The Bicubic method is approximately twice as slow as Bilinear and 4 times as slow as NN, but supposedly offers the highest quality. In many cases, however, it provides little, if any, noticeable improvement over the Bilinear method.
Default: 1 (Bilinear).
See also: Section 4.1 - Resizing Algorithms.
Returns the number of original color components for the image: 3 for RGB, 4 for CMYK and 1 for grayscale images. This property is not affected by a successful call to ToRGB or ToGrayscale.
Returns the format of the currently opened image. Possible values are "JPG", "GIF", "PNG", "BMP" and "TIF" for JPEG, GIF, PNG, BMP and TIFF formats, respectively.
Returns the original image height (in pixels).
See also: Section 2.1 - Thumbnail-Creating Steps.
Returns the original image resolution along the X-axis (in DPI). If this property returns 1, the resolution may be available via an EXIF tag, or not available at all (in the latter case it should be assumed to be 72 DPI).
See also: Section 8.2 - Image Resolution.
Returns the original image resolution along the Y-axis (in DPI). If this property returns 1, the resolution may be available via an EXIF tag, or not available at all (in the latter case it should be assumed to be 72 DPI).
See also: Section 8.2 - Image Resolution.
Returns the original image width (in pixels).
See also: Section 2.1 - Thumbnail-Creating Steps.
Specifies the output format as the JpegImageFormat enumerator object. The valid values are: JpegImageFormat.Jpeg (0), JpegImageFormat.Png (1) and JpegImageFormat.Bmp (2). JpegImageFormat.Jpeg by default. Side effect: setting this property to JpegImageFormat.Png sets the PNGOutput property to True.
Sets or retrieves the color components of an individual pixel specified via 0-based (X, Y) coordinates. This property returns, or is assigned, a byte array of color components. The size of the array must match this image's color space (3 items for RGB, 4 for CMYK, 1 for grayscale). The X and Y coordinates must be in the range (0, Width - 1) and (0, Height - 1), respectively. Since the Pixels property is an alias for the indexer, the word "Pixels" can be omitted.
See also: Section 8.3 - Access to Individual Pixels.
If set to true, the image is saved in the PNG format instead of JPEG. The alpha channel, if any, is preserved. False by default. Setting this property to True has the side effect of setting the OutputFormat property to JpegImageFormat.Png.
See also: Chapter 10 - PNG Output.
False by default. If set to true, creates a link between the Width and Height properties so that changing one dimension will automatically change the other to preserve the original aspect ratio of the image.
See also: Section 2.1 - Thumbnail-Creating Steps.
False by default. If set to true, generates a progressive JPEG image, i.e. an image that progressively gets sharper on the web page as it is being downloaded. This property has no effect if the output format is PNG or BMP.
See also: Section 8.4 - Progressive JPEGs.
Specifies the degree of compression loss. Affects the resultant JPEG image quality and file size.
Accepts an integer value in the range 0 to 100, 0 being the lowest quality, highest loss and smallest file size. The higher the value the higher the image quality, and the larger the file size.
This property is set to 80 by default which offers a close-to-optimal combination of image quality and file size.
This property has no effect if the output format is PNG or BMP.
See also: Section 4.5 - Adjusting Image Compression.
Specifies a new image resolution along the X-axis in DPI.
See also: Section 8.2 - Image Resolution.
Specifies a new image resolution along the Y-axis in DPI.
See also: Section 8.2 - Image Resolution.
If the currently opened image is a GIF which has a transparency color, this property returns this color as a long integer in the format &H00rrggbb. If the image does not have a transparency color, this property will throw an error. Always check the property TrasparencyColorExists before retrieving the transparency color of the image. This property was introduced by version 1.6.
See also: Section 6.2 - GIF Transparency.
Returns true if the currently opened image is a GIF with a transparency color. Returns false otherwise. Check this property before attempting to access TransparencyColor.
Specifies a new image width (in pixels).
Side effect: if PreserveAspectRatio is set to true, changing this property automatically changes Height to preserve the original aspect ratio of the image.
See also: Section 2.1 - Thumbnail-Creating Steps.
Methods
Adds or replaces an IPTC item in the current image. ID must be an IPTC field name from the table shown in Section 7.3 - IPTC Item List. Value is a string to be inserted into this field. Value cannot be longer than 1000 characters.
To use this method, the property JpegManager.PreserveMetadata must be set to true before the image is opened.
When ID is set to "IptcCopyrighted", Value must be set to either "True" or "False".
If ID is set to "IptcKeywordsAdd", adds a new "IptcKeywords" entry instead of replacing an existing one. If ID is set to "IptcKeywordsRemove", removes all existing keywords so that a whole new set of keywords can be specified.
See also: Section 7.6 - Metadata Editing.
A multi-purpose method which adjusts brightness, contrast and saturation of an RGB image.
Function specifies the operation code: 1 for brightness, 2 for contrast and 3 for saturation. Value specifies the operation-specific value: a number in the range [-1, 1] for brightness and saturation, and in the range [0.001, 5] for contrast.
This method is obsolete, use the method ApplyFilter instead.
See also: Section 8.5 - Brightness, Contrast and Saturation.
Replaces the color values of each pixel of the current image with the respective values of its alpha channel. Thus the alpha channel becomes an image in its own right (in grayscale color space.) This method is useful if the alpha channel of an image needs to be drawn on. If the image has no alpha channel, this method throws an exception.
See also: Section 10.3 - Alpha Channel Management.
Implements several common image filters, such as brightness, contrast, blur, etc. FilterID specifies which filter to use. Param, Param1 and Param2 are filter-specific parameter values. All currently implemented filters, their parameters and sample output are described here.
See also: Section 8.6 - Filters.
Rotates and/or flips the image according to the embedded EXIF Orientation tag, and then resets this tag to the default value of 1. This makes the image viewable in a consistent manner across all image viewers and platforms. Returns the original Orientation value of the image, or 0 if none was present. For this property to work, the JpegManager.PreserveMetadata must be set to true before the image is opened.
See also: Section 7.8 - EXIF Editing.
Sets or changes the embedded EXIF field specified by Name. The Value argument specifies a numeric or string value. If the image does not have an EXIF data block to begin with, this method creates it automatically. For this property to work, the JpegManager.PreserveMetadata must be set to true before the image is opened.
See also: Section 7.8 - EXIF Editing.
Cuts off edges from the thumbnail. For this method to take effect, you must call it before calling .Save, .SendBinary or .Binary.
The arguments (x0, y0) and (x1, y1) are the coordinates of the upper-left and lower-right corners of the desired cropped image within the thumbnail.
See also: Section 4.3 - Image Cropping.
Combines the pixels of the current image with the specified background Color in accordance with the current alpha channel, and then removes the alpha channel. Has no effect if the image has no alpha channel. This method is useful for converting PNG images to JPEG format.
See also: Section 10.3 - Alpha Channel Management.
Flips the resultant thumbnail horizontally. For this method to take effect, you must call it before calling .Save, .SendBinary or .Binary.
See also: Section 4.4 - Image Flipping and Rotation.
Flips the resultant thumbnail vertically. For this method to take effect, you must call it before calling .Save, .SendBinary or .Binary.
See also: Section 4.4 - Image Flipping and Rotation.
Returns a new instance of the JpegImage object containing the alpha channel of this image. The image returned by this method is always in the grayscale color space. Throws an exception if this image contains no alpha channel.
Turns a color image into grayscale. Method specifies the conversion algorithm. Valid values: 0 (desaturation), 1 (recommended algorithm) and 2 (a slight variation of Method 1). If Method is not specified, it is assumed to be 1. The underlying image remains in the original color space.
See also: Section 4.6 Grayscale Conversion.
Removes the current alpha channel from the image. Does nothing if the image has no alpha channel.
See also: Section 10.3 - Alpha Channel Management.
Assigns the color NewColor to all pixels of the given color OldColor. The old and new colors are to be specified as long integers with the most significant 8 bits set to Hex FF (0xFFxxxxxx), such as 0xFFFF0000 (red), 0xFF00FF00 (green), 0xFF0000FF (blue), etc.
Rotates the image by an arbitrary angle specified by Angle (in degrees). A positive number specifies a counter-clockwise rotation, a negative number clockwise rotation. Color specifies the fill color for the four triangular corner areas formed by the rotation.
This method causes the Width and Height properties to increase as the image canvas has to expand horizontally and vertically to accommodate the slanted image. This method also adds an alpha channel to the image making the corner areas fully transparent. To take advantage of the alpha channel, the rotated image has to be saved in PNG format (PNGOutput property should be set to true.)
See also: Section 10.4 - Using PNG Format for Image Rotation.
Rotates the image 90 degrees counter-clockwise. This method also causes the properties Width and Height to switch values. For this method to take effect, you must call it before calling .Save, .SendBinary, or .Binary.
See also: Section 4.4 - Image Flipping and Rotation.
Rotates the image 90 degrees clockwise. This method also causes the properties Width and Height to switch values. For this method to take effect, you must call it before calling .Save, .SendBinary or .Binary.
See also: Section 4.4 - Image Flipping and Rotation.
Resizes the currently opened image using parameters specified by various properties. Saves the resultant image thumbnail to a file specified by Path. If a file with this name already exists it will be overwritten.
See also: Section 2.1 - Thumbnail-Creating Steps.
Same as Save but generates a unique filename if the file specified by Path already exists. A unique name is generated to avoid overwriting an existing file by appending a number in parentheses after the filename, such as image(1).jpg, image(2).jpg, etc.
Returns the filename (without the path) under which the image ends up being saved.
See also: Section 2.1 - Thumbnail-Creating Steps.
Resizes the currently opened image using parameters specified by various properties. Sends the resultant image directly to the client browser by internally calling Response.BinaryWrite. Automatically sets the Content-Type header to "image/jpeg", "image/png" or "image/bmp" depending on the current output format.
If ContentDisposition is specified, also sets the "Content-Disposition" header to a value specified by this argument. A typical value for this argument is
"filename=image_name.jpg"or
"attachment;filename=image_name.jpg"This method can only be used in an ASP.NET/IIS environment.
See also: Section 2.2 - Sending Thumbnails Directly to the Browser.
Applies the "Sepia" filter to an image which makes it look like an old photograph. Hue controls the brownish hue of the output image. Recommended range: 25 to 60. Contrast specifies the degree of contrast adjustment. Recommended range: 1.2 to 1.5.
See also: Section 4.7 - Sepia Filter.
Sets the alpha channel for the current image. Image must be another instance of the JpegImage object. It must be in the grayscale color space. To convert any image to grayscale, use the ToGrayscale method. The dimensions of Image must match that of the current image.
If Inverse is false, the pixel values of Image are used directly to form the alpha channel (0 corresponds to full transparency and 255 to full opacity.) If Inverse is true, the values are inverted.
If Image is Nothing (null), an alpha channel with all values set to 255 is created (or 0 if Inverse is true.)
An alpha channel only has effect if the image is saved in the PNG format (PNGOutput property is set to true.)
See also: Section 10.3 - Alpha Channel Management.
Sharpens an image. Radius specifies the radius of scanning (in pixels) around each pixel. This argument should normally be set to 1 or 2. Amount specifies the degree of sharpness (in %). This argument must be greater than 100. For this method to take effect, you must call it before calling .Save, .SendBinary or .Binary.
See also: Section 4.2 - Image Sharpening.
Converts an image into the grayscale color space (1 byte per pixel.) Method specifies the conversion algorithm. Valid values: 0 (desaturation), 1 (recommended algorithm) and 2 (a slight variation of Method 1). Unlike the Grayscale method, reduces the number of bytes per pixel to 1. This method is useful for alpha channel management.
See also: Section 10.3 - Alpha Channel Management .
Converts a CMYK or grayscale image into the RGB color space. Does nothing if the image is already an RGB one. Use this method to create Web-viewable RGB thumbnails of CMYK images. Note that it is more efficient to call this method after setting new Width and Height properties.
See also: Section 8.1 - CMYK-to-RGB Conversion.
