DEV Community: Dmitry Matuzko

Creation and validation of geometry in Aspose.GIS

Dmitry Matuzko — Tue, 20 Nov 2018 12:55:02 +0000

Aspose.GIS handles geospatial data in a common way regardless of storage format, as all the GIS data formats store, in principle, the same kind of data. As such, methods to create and check geometric data are not coupled to format and can be used in any case. In this article I will overview how to create geometric data in Aspose.GIS and check its validity.

Creation of Point, LineString and Polygon

Point is just a point, LineString is a polyline - a series of connected points, ang Polygon is basically an area enclosed by closed polyline. As such, Point can be instantiated with default values, from another point, or by passing X, Y and optional Z and M coordinates. LineString can be created by instantiating it and then adding points to it - either passing a Point to AddPoint, or just passing coordinates.

Here is an example of creation of Point and LineString:

Point point = new Point(40.7128, -74.006);

LineString line = new LineString();

line.AddPoint(78.65, -32.65);

line.AddPoint(-98.65, 12.65);

line.AddPoint(point);

Polygon is a bit more complex. It has outer boundary, a closed polyline represented as LinearRing instance - this class is a LineString that ensures it's closed and doesn't self-intersect -, and it can have multiple inner boundaries, essentially "holes" in its geometry. These are also represented by LinearRing instances. External boundary is placed at ExteriorRing property, while interior rings are accessed by AddInteriorRing and GetInteriorRing methods, with only total count represented as InteriorRingsCount property. Look at the example on creating a polygon with a hole:

Polygon polygon = new Polygon();

LinearRing ring = new LinearRing();
ring.AddPoint(50.02, 36.22);
ring.AddPoint(49.99, 36.26);
ring.AddPoint(49.97, 36.23);
ring.AddPoint(49.98, 36.17);
ring.AddPoint(50.02, 36.22);

LinearRing hole = new LinearRing();
hole.AddPoint(50.00, 36.22);
hole.AddPoint(49.99, 36.20);
hole.AddPoint(49.98, 36.23);
hole.AddPoint(50.00, 36.24);
hole.AddPoint(50.00, 36.22);

polygon.ExteriorRing = ring;
polygon.AddInteriorRing(hole);

Creation of geometry collection

Geometry collection is created in obvious way, create a collection and add elements to it:

Point point = new Point(40.7128, -74.006);

LineString line = new LineString();
line.AddPoint(78.65, -32.65);
line.AddPoint(-98.65, 12.65);

GeometryCollection geometryCollection = new GeometryCollection();
geometryCollection.Add(point);
geometryCollection.Add(line);

Typed geometry collections

There are special collections that only accept the corresponding kind of geometry element: MultiLineString, MultiPoint and MultiPolygon. These only accept LineString, Point and Polygon accordingly:

MultiPoint multipoint = new MultiPoint();
multipoint.Add(new Point(1, 2));
multipoint.Add(new Point(3, 4));

            LineString firstLine = new LineString();
firstLine.AddPoint(7.5, -3.5);
firstLine.AddPoint(-9.6, 12.6);

LineString secondLine = new LineString();
secondLine.AddPoint(8.5, -2.6);
secondLine.AddPoint(-8.6, 1.5);

MultiLineString multiLineString = new MultiLineString();
multiLineString.Add(firstLine);
multiLineString.Add(secondLine);

            LinearRing firstRing = new LinearRing();
firstRing.AddPoint(8.5, -2.5);
firstRing.AddPoint(-8.5, 2.5);
firstRing.AddPoint(8.5, -2.5);
Polygon firstPolygon = new Polygon(firstRing);

LinearRing secondRing = new LinearRing();
secondRing.AddPoint(7.6, -3.6);
secondRing.AddPoint(-9.6, 1.5);
secondRing.AddPoint(7.6, -3.6);
Polygon secondPolygon = new Polygon(secondRing);

MultiPolygon multiPolygon = new MultiPolygon();
multiPolygon.Add(firstPolygon);
multiPolygon.Add(secondPolygon);

As you can see, creating geometry is easy.

Geometry validation

Validation checks wether geometric data in an geometry instance is correct for the type of that instance, i.e. a polygon has an external boundary, a LinearRing is enclosed, etc. It is performed automatically and result is availible at IsValid property. Take a look:

LinearRing linearRing = new LinearRing();
linearRing.AddPoint(0, 0);
linearRing.AddPoint(0, 1);
linearRing.AddPoint(1, 0);
bool valid = linearRing.IsValid; // valid == false , as ring is not enclosed
linearRing.AddPoint(0, 0);
valid = linearRing.IsValid; // valid == true, as ring is now enclosed

Additionally, there is a check for simplicity, in terms of - like no self-intersections, etc. It works same way as validation and availible at IsSimple property.:

            LineString lineString = new LineString();
            bool simple = lineString.IsSimple; // simple == true
            lineString.AddPoint(0, 0);
            lineString.AddPoint(1, 0);
            simple = lineString.IsSimple; // simple == true
            lineString.AddPoint(0.5, 0);
            simple = lineString.IsSimple; // simple == false (line string crosses itself)

That's all for now, stay tuned!

For more examples please visit the Aspose.GIS GitHub page. There's also Twitter and Facebook pages for news on Aspose.GIS.

Reviewing TIFF options in detail

Dmitry Matuzko — Wed, 14 Nov 2018 08:59:03 +0000

Aspose.Imaging uses ImageOptionsBase-based objects to set up file formats when saving or creating images. TIFF format, as such, is configured via instances of TiffOptions class. As I've noted in previous article, TiffOptions can also be read from loaded image, so you can get information about format's settings for the particular file. Most of the properties of TiffOptions apply to indivitual TiffFrames, with only few properties related to TiffImage as a collection of TiffFrames. Given multi-image nature of TIFF, I will refer to whole TIFF, represented as TiffImage as "file", and to individual images within, represented as TiffFrame, as "image" or "page".

TiffOptions provides facility to set up TIFF file format as you need. Most of the often used options are supported explicitly and are availible as properties. Changes applied to them will result in according processing of the image data, if needed. TiffOptions also provides a way of working directly with TIFF tags, so anything not explicitly supported by Aspose.Imaging can also be worked upon.

Here I will first describe the properties of TiffOptions, and after them I'll describe the TIFF-specific methods of TiffOptions, they are related to direct access to tag data.

Properties

Here are descriptions of explicitly availible properties specific to TiffOptions, roughly grouped by their scope

Metadata

Artist

Person who created the image.

Copyright

DateTime

Date and time of image creation.

DocumentName

The name of the document from which this image was scanned.

ExifIfd

Pointer to EXIF IFD of the TIFF file.

FileStandard

Either TIFF 6.0 Baseline or TIFF 6.0 Extended.

ImageDescription

The title of the image - comment or such. No 2-byte characters allowed.

InkNames

Names of the inks used in this image. Inks are colors of Separate photometric model.

PageName

Name of the page from which this image was scanned.

PageNumber

Page number of the page from which this image was scanned.

ScannerManufacturer

Name of the manufacturer of the scanner used to scan this image.

ScannerModel

Model of the scanner used to scan this image.

SoftwareType

Name and version of software that created this image (or firmware if created by hardware).

TargetPrinter

Description of the supposed printing environment.

XmpData

Metadata in XMP format, represented as XmpPacketWrapper (Aspose.Imaging API object to work with XMP metadata)

Dimension and positioning data

Orientation

Rotation and mirroring of the image.

ResolutionUnit

Resolution unit for the image - inch, centimeter etc.

Xposition

Offset of the left side of the image from the left side of the page it's on.

Xresolution

Resolution in pixels per resolution unit along horizonal axis.

Yposition

Offset of the top side of the image from the top side of the page it's on. TIFF's Y axis is downward, so this is positive value.

Yresolution

Resolution in pixels per resolution unit along vertical axis.

Image format

AlphaStorage

Defines how alpha is stored - premultiplied or not. Used when there are more than 3 samples per pixel.

BitsPerPixel

Amount of bits constituting data for single pixel, calculated from BitsPerSample and SamplesPerPixel.

BitsPerSample

Number of bits per color component. This is an array, as each component can have different bit count. When this is set, SamplesPerPixel will be set to array's length.

ByteOrder

This is a per-file setting, not per-image, describes endianness of the file.

Compression

Compression method used for image raster data.

FaxT4Options

Options for Group 3 Fax compression (T4) - 1D compression, 2D compression, no compression, or filling bits to byte boundaries (expanding data size).

FillOrder

Order of bits within bytes

IsExtraSamplesPresent

True if there are more samples in SamplesPerPixel than required by photometric setting.

IsTiled

True for tiled images. Large TIFF images are often split into tiles, which can reduce memory use when only part of the image has to be displayed/processed at once.

Photometric

Color space of the image data. BW with minimum as white, BW with minimum as black, RGB, paletted color, transparency mask (obsolete in TIFF v6.0), separate colors (typically used for CMYK), YCbCr, Cielab, Icclab, Itulab, Logl and Logluv are supported by Aspose.Imaging.

PlanarConfiguration

Describes wether colors are stored on separate planes or interleaved.

Predictor

Predictor for LZW compression - either none, or hozirontal difference.

SampleFormat

Numeric format of the sample - unsigned integer, signed integer, floating point, untyped, complex integer, complex floating point. Separate for each component.

SamplesPerPixel

Number of color components per pixel.

SubFileType

Type of data stored in subfile. Either just an image, thumbnail for another image in file, page, transparency mask or MRC image.

YCbCrCoefficients

Coefficients for transformation of RGB data to YCbCR.

YCbCrSusbsampling

Subsampling used for YCbCr image data.

Image data layout

It is closely related to image format, as it also outlays how raster data is located in file.

ImageLength

Height of the image in pixels as stated in TIFF tag.

ImageWidth

Width of the image in pixels as stated in TIFF tag.

RowsPerStrip

TIFF images can be organised into strips for faster IO and easier random access. This tag describes count of rows (lines) of image in single strip. Total count of strips per image can be calculated as follows: StripsPerImage = floor ((ImageLength + RowsPerStrip - 1) / RowsPerStrip).

StripOffsets

Offsets of the strips constituting the image, relative to beginning of file. This is used to locate actual image data in file, unless tiling is used, then TileOffsets is used.
It is recommended to keep array below 64k bytes in length, and keep strips below 64k bytes each as well.

StripByteCounts

Number of bytes in strips after compression.

TileWidth

Width of a tile in pixels (number of columns in a tile).
Horizontal, vertical and total tile counts can be calculated as follows:
TilesAcross = (ImageWidth + TileWidth - 1) / TileWidth
TilesDown = (ImageLength + TileLength - 1) / TileLength
TilesPerImage = TilesAcross * TilesDown.
Must be multiple of 16. Might be larger than ImageWidth, but this means either tiles are too large, or image is too small, so tiling is not optimal

TileLength

The tile length (height) in pixels. This is the number of rows(lines) in each tile. Must be a multiple of 16.

TileOffsets

Offsets of tiles in file, relative to beginning of file. Tiles are ordered left-to-right and top-to-bottom. If planar configuration is used, first series of offsets point to tiles of first component plane, then second series for second plane etc, so total count of offsets is total count of tiles multiplied by samples per pixel.

TileByteCounts

Count of bytes in tile after compression.

Color profiling and processing

ColorMap

Palette used for the image if it is paletted, as stored in file. Palette property is already loaded and processed palette. Length must correspond to formula: 3*(2^BitsPerSample).

IccProfile

Stream of color profile embedded in the image.

HalfToneHints

Values to control halftone function.

MaxSampleValue

Maximum allowed sample value in image, per each channel. 16-bit version.

MinSampleValue

Minimum allowed sample value in image, per each channel. 16-bit version.

PremultiplyComponents

Wether components must be premultiplied by color profile data.

SmaxSampleValue

Maximum allowed sample value in image, per each channel. 32-bit version.

SminSampleValue

Minimum allowed sample value in image, per each channel. 32-bit version.

Threshholding

Describes method used to convert grayscale images to BW.

Tag data

IsValid

True if this TiffOptions instance is validly formed, as some options might be conflicting. Use Validate() method to see errors.

ValidTagCount

Count of valid TIFF tags in image, i.e. tags, that can be saved.

Whole file-related properties

ByteOrder

Repeating here, as it is actually TiffImage related - the only format property that is set for the whole file, not in pages's tags.

TotalPages

Just the count of pages in document, as such, is read-only, as it is changed when you add or remove pages.

Methods

Here are descriptions of TiffOptions-specific methods, mostly working with "raw" tags. Tags are stored as instances of descendants of TiffDataType class, they provide access to tag ID, type and value within the tag. Known tag ID list is availible as TiffTags enum.

AddTag

Adds new tag to image.

AddTags

Adds an array of tags to the image.

GetTagByType

Returns instance of tag by tag's ID, or null if no such tag is present.

GetValidTagCount

Returns count of valid tags in provided array of tags.

IsTagPresent

Checks if image contains tag with specified tag ID.

RemoveTag

Removes tag by tag ID.

Validate

Checks if combination of tags in this TiffOptions is valid.

That's all for now, stay tuned!

For more examples please visit the Aspose.Imaging GitHub page. There's also Twitter and Facebook pages for news on Aspose.Imaging.

Clarifying working with TIFF in Aspose.Imaging

Dmitry Matuzko — Mon, 12 Nov 2018 20:18:39 +0000

Aspose.Imaging provides support for TIFF format, which can be considered a "classic" format for raster data interchange originally used for scanning and faxing and is now used in many polygraphic, scientific and in general image processing applications that require higher precision and adjustability than common image formats like JPEG and PNG that are more end-user oriented.

Given the flexibility of TIFF format, it might not be obvious how to properly work with this format in general and in Aspose.Imaging as well. As such, this article will explain some basic concepts of TIFF and how to work with it in Aspose.Imaging. There will be a further article that will dive deeper on options availible for TIFF in Aspose.Imaging.

Multiple images in one file

Unlike most other raster image formats, TIFF is essentially a container for multiple separate raster images, with each image having its own set of header tags, that describe different properties of image: size, definition, compression, data arrangement - pixel order, byte order, bit per pixel/channel count, etc.
As such, in Aspose.Imaging, these contained images are represented by a specific TiffFrame class, that exposes most of the TIFF-specific properties. TiffImage class contains an array of TiffFrame instances in Frames property. The TiffImage class also has to expose some of these properties that are common for all raster formats, such as size, but they are mapped to ActiveFrame, one of TiffFrame instances in the Frames property that is selected as active, by default it is the first element of Frames array. Same happens when you access TiffImage instance as RasterImage or Image.
As such, in Aspose.Imaging, TiffFrame is what you have to work with if you really want to work with TIFF-specific properties, while TiffImage is just a collection with some compatibility measures. You can work on it like on other Image's subclasses, but select specific ActiveFrame you want to work on first.
Example on using TiffFrame and ActiveFrame:

// Create instances of FileStream and initialize with Tiff images
FileStream fileStream = new FileStream("TestDemo.tif", FileMode.Open);
FileStream fileStream1 = new FileStream("sample.tif", FileMode.Open);

// Create an instance of TiffImage and load the destination image from filestream
using (TiffImage image = (TiffImage) Image.Load(fileStream))
{
    // Create an instance of TiffImage and load the source image from filestream
    using (TiffImage image1 = (TiffImage) Image.Load(fileStream1))
    {
        // Create an instance of TIffFrame and copy active frame of source image
        TiffFrame frame = TiffFrame.CopyFrame(image1.ActiveFrame);

        // Add copied frame to destination image
        image.AddFrame(frame);
    }

    // Save the image with changes
    image.Save("ConcatenatingTIFFImagesfromStream_out.tif");

    // Close the FileStreams
    fileStream.Close();
    fileStream1.Close();
}

Creating TiffImage and TiffFrame

As such, TiffImage is created in a different way from other RasterImage's. You either create an empty TiffImage with parameterless constructor, or a TiffImage with single contained raster by constructor that accepts single TiffFrame, or a TiffImage with multiple rasters by constructor that accepts array of TiffFrame. Actual options, like pixel format, image size etc. are reserved for TiffFrame.

TiffFrame, being a real image, is created more like other RasterImage descendants: you can create an new one from existing image (by path to image file, by stream of image file, or already loaded RasterImage instance), you can specify TiffOptions and dimensions to create a completely new empty image, and create new image from existing one while at once specifying TiffOptions (also with three variants of how to specify the source), so that you can load your image raster data into desired format of TIFF.

// Create an instance of TiffOptions and set its various properties
// The options themselves will be described in following article on TiffOptions
TiffOptions options = new TiffOptions(TiffExpectedFormat.Default);
options.BitsPerSample = new ushort[] { 8, 8, 8 };
options.Photometric = TiffPhotometrics.Rgb;
options.Xresolution = new TiffRational(72);
options.Yresolution = new TiffRational(72);
options.ResolutionUnit = TiffResolutionUnits.Inch;
options.PlanarConfiguration = TiffPlanarConfigs.Contiguous;

// Set the Compression to AdobeDeflate
options.Compression = TiffCompressions.AdobeDeflate;

// Or Deflate                        
// Options.Compression = TiffCompressions.Deflate;

// Create a new TiffImage with specific size and TiffOptions settings
// via creating TiffFrame with that size and options
using (TiffImage tiffImage = new TiffImage(new TiffFrame(options, 100, 100)))
{
    // Loop over the pixels to set the color to red
    for (int i = 0; i < 100; i++)
    {
        tiffImage.ActiveFrame.SetPixel(i, i, Color.Red);
    }
    // Save resultant image
    tiffImage.Save("output.tiff");
}

TiffFrame properties

TiffFrame is actually a descendant of RasterImage (or, more specifically, RasterCachedImage), and as such, for the most part, it can be handled like any other RasterImage instance.
The differences from a RasterImage are that TiffFrame has ExifData property, which contains EXIF metadata as an ExifData instance, and, expectedly, FrameOptions property, which contains TiffOptions instance describing frame's TIFF-related properties. GetOriginalOptions method, however, does the same, it is just not explicitly typed as TiffOptions. This is what you want to use if you need to get TIFF's format properties of the image.
Also, there are two new methods for TiffFrame:

CopyFrame

Creates an identical copy of the frame. This has been used in examples above.

CreateFrameFrom

Creates new frame, like CopyFrame, but with properties specified in TiffOptions, so you can use it co convert to different pixel format.

Example on getting compression method of TIFF frames:

using (TiffImage tiff = (TiffImage)Image.Load("TiffCompressed.tiff"))
{
    foreach(TiffFrame frame in tiff.Frames)
    {
        Console.WriteLine(frame.FrameOptions.Compression.ToString());
    }
}

TiffImage properties

As said before, TiffImage retains most of the RasterImage's methods and properties, but only applies them to the current ActiveFrame. Most of the TiffImage-specific additions are related to the TiffImage being a collection of images. The only exception being the ByteOrder property, which defines endianness of the data in file, and is applied for all the file's contents, so TiffFrame's don't have that property. TiffOptions do specify this property, as TIFF images can be also creating by just saving a loaded image of any format using Save() method with a TiffOptions instance, and not by frame-by-frame approach. In that case, all frames within file will have identical parameters. Other two properties are already described ActiveFrame and Frames.
TiffImage's new methods haven't been descried yet, so there they are:

Add

Adds all frames of provided TiffImage to the end of Frames array of current image.

AddFrame

Adds the provided TiffFrame to the end of Frames array of current image.

AddFrames

Adds provided array of TiffFrame to the end of Frames array of current image.

InsertFrame

Inserts provided TiffFrame into specified index of Frames array.

RemoveFrame

Removes frame either by index or by instance.

There are also several helper methods that work on all frames at once:

AlignResolutions

Makes vertical and horizontal resolutions of all frames equal

ResizeProportional

Resizes all frames of image according to the ratio of newWidth/width and newHeight/height.

RotateFlipAll

Rotates/flips all frames of the image.

Extracting frames from TIFF and saving them as separate images

Here is an example on how to save different frames of TIFF to different BMP files:

using (TiffImage multiImage = (TiffImage)Image.Load("SampleTiff1.tiff"))
{
    // Create an instance of int to keep track of frames in TiffImage
    int frameCounter = 0;

    // Iterate over the TiffFrames in TiffImage
    foreach (TiffFrame tiffFrame in multiImage.Frames)
    {
        multiImage.ActiveFrame = tiffFrame;

        // Load Pixels of TiffFrame into an array of Colors
        Color[] pixels = multiImage.LoadPixels(tiffFrame.Bounds);

        // Create an instance of bmpCreateOptions
        BmpOptions bmpCreateOptions = new BmpOptions();
        bmpCreateOptions.BitsPerPixel = 24;

        // Set the Source of bmpCreateOptions as FileCreateSource by specifying the location where output will be saved
        bmpCreateOptions.Source = new FileCreateSource(string.Format("ConcatExtractTIFFFramesToBMP_out{0}.bmp", frameCounter), false);

        // Create a new bmpImage
        using (BmpImage bmpImage = (BmpImage)Image.Create(bmpCreateOptions, tiffFrame.Width, tiffFrame.Height))
        {
            // Save the bmpImage with pixels from TiffFrame
            bmpImage.SavePixels(tiffFrame.Bounds, pixels);
            bmpImage.Save();
        }
        frameCounter++;
    }
}

That's all for now, the following article will describe TiffOptions in depth!

For more examples please visit the Aspose.Imaging GitHub page. There's also Twitter and Facebook pages for news on Aspose.Imaging.

Geometry analysis features in Aspose.GIS

Dmitry Matuzko — Wed, 24 Oct 2018 11:38:28 +0000

Aspose.GIS doesn't only convert geospatial data between file formats and allows to create and read the data, it also allows some analysis of the data. Here I'll describe gow Aspose.GIS can be used for geospatial data analysis in more detail.

Geospatial features are represented as subclasses of Geometry class - Point, Surface, LineString (polyline), LinearRing, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection. The methods used for analysis are provided by Geometry class and thus are availible for any geospatial feature. In this article I'll describe what methods are provided by Geometry class for analysis.

Properties

For the beginning, let'w review what properties the Geometry class provides:

CoordinateDimension

Gets number of coordinate dimensions of this geometry. I.e. 2 if there are only X and Y coordinates, 3 if there are X, Y and Z or M coordinate, etc.

Dimension

Gets topological dimension of the geometry - i.e. if it is a point, line or surface.

GeometryType

Gets type of geometry - essentially name of the class of the instance - if it is a Polygon, GeometryType will return GeometryType.Polygon.

HasM

Gets wether this geometry has M coordinate.
An M coordinate (measure) is a value that conveys information about a geographic feature and that is stored together with the coordinates that define the feature's location.
For example, suppose that you are representing highways in your application. If you want your application to process values that denote linear distances or mileposts, you can store these values along with the coordinates that define locations along the highway.

HasZ

Gets wether this geometry has Z coordinate (elevation).

IsEmpty

Gets wether this geometry is empty (i.e. contains no geospatial data).

IsSimple

Gets wether this geometry is simple in SFA terms.
Here is an example:

LineString lineString = new LineString();
bool simple = lineString.IsSimple; // simple == true
lineString.AddPoint(0, 0);
lineString.AddPoint(1, 0);
simple = lineString.IsSimple; // simple == true
lineString.AddPoint(0.5, 0);
simple = lineString.IsSimple; // simple == false (line string crosses itself)

IsValid

Gets wether this geometry is valid.
Here is an example:

LinearRing linearRing = new LinearRing();
linearRing.AddPoint(0, 0);
linearRing.AddPoint(0, 1);
linearRing.AddPoint(1, 0);
bool valid = linearRing.IsValid; // valid == false
linearRing.AddPoint(0, 0);
valid = linearRing.IsValid; // valid == true

Null

Static method that returns null geometry.

SpatialReferenceSystem

Gets SpatialReferenceSystem of this Geometry. It can be null, if SRS is not known. Assigning new SRS won't perform any transformation, only reference will be changed.

Methods for basic property analysis

GetArea

Gets area of the geometry, if it is a collection, then sum of all areas.

GetDistanceTo

Gets closest distance from this geometry to specified other geometry. If at least one of geometries is empty, returns -1.

GetLength

Gets length of the geometry. If it is a Polygon, then returns perimeter. If it is a collection, then returns sum of all lengths.

Methods for boolean relationships

CoveredBy

Returns true if this geometry is spatially covered by another geometry, otherwise false.

Covers

Returns true is this geometry spatially covers the other geometry. Essentially same as CoveredBy with this and other geometries swapped.

Crosses

Tests wether two geometries cross, i.e. they have some but not all interior points in common, and dimension of the intersection is smaller than dimension of at least one of geometries, i.e. for example intersection is a line while one of geometries is a surface.
Here is an example:

var geometry1 = new LineString();
geometry1.AddPoint(0, 0);
geometry1.AddPoint(2, 2);

var geometry2 = new LineString();
geometry2.AddPoint(1, 1);
geometry2.AddPoint(3, 3);

Console.WriteLine(geometry1.Crosses(geometry2)); // False

var geometry3 = new LineString();
geometry3.AddPoint(0, 2);
geometry3.AddPoint(2, 0);

Console.WriteLine(geometry1.Crosses(geometry3)); // True

Disjoint

Returns true if two geometries have no common points.

Intersects

The reverse of Disjoint.
Here is an example:

var geometry1 = new Polygon(new LinearRing(new[]
{
    new Point(0, 0),
    new Point(0, 3),
    new Point(3, 3),
    new Point(3, 0),
    new Point(0, 0),
}));

var geometry2 = new Polygon(new LinearRing(new[]
{
    new Point(1, 1),
    new Point(1, 4),
    new Point(4, 4),
    new Point(4, 1),
    new Point(1, 1),
}));

Console.WriteLine(geometry1.Intersects(geometry2)); // True
Console.WriteLine(geometry2.Intersects(geometry1)); // True

// 'Disjoint' is opposite to 'Intersects'
Console.WriteLine(geometry1.Disjoint(geometry2)); // False

Overlaps

Tests wether geometries overlap, as in they have some interior points in common and intersection has same dimension as geometries, i.e. for example geometries are surfaces and intersection is a surface too. Always false if geometries are of different dimensions.
Here is an example:

var geometry1 = new LineString();
geometry1.AddPoint(0, 0);
geometry1.AddPoint(0, 2);

var geometry2 = new LineString();
geometry2.AddPoint(0, 2);
geometry2.AddPoint(0, 3);

Console.WriteLine(geometry1.Overlaps(geometry2)); // False

var geometry3 = new LineString();
geometry3.AddPoint(0, 1);
geometry3.AddPoint(0, 3);

Console.WriteLine(geometry1.Overlaps(geometry3)); // True

SpatiallyContains

Tests if this geometry spatially contains another.
Here is an example:

var geometry1 = new Polygon();
geometry1.ExteriorRing = new LinearRing(new[]
{
    new Point(0, 0),
    new Point(0, 4),
    new Point(4, 4),
    new Point(4, 0),
    new Point(0, 0),
});
geometry1.AddInteriorRing(new LinearRing(new[]
{
    new Point(1, 1),
    new Point(1, 3),
    new Point(3, 3),
    new Point(3, 1),
    new Point(1, 1),
}));

var geometry2 = new Point(2, 2);

Console.WriteLine(geometry1.SpatiallyContains(geometry2)); // False

var geometry3 = new Point(0.5, 0.5);
Console.WriteLine(geometry1.SpatiallyContains(geometry3)); // True

// 'a.SpatiallyContains(b)' equals to 'b.Within(a)'
Console.WriteLine(geometry3.Within(geometry1)); // True

SpatiallyEquals

Tests if two geometries are spatially equal. Essentially, tests if two geometries occupy same space when projected onto two-dimensional space. Here is an example:

var geometry1 = new MultiLineString
{
    new LineString(new [] { new Point(0, 0), new Point(1, 1) }),
    new LineString(new [] { new Point(1, 1), new Point(2, 2) }),
};

var geometry2 = new LineString(new[]
{
    new Point(0, 0), new Point(2, 2),
});

Console.WriteLine(geometry1.SpatiallyEquals(geometry2)); // True

geometry2.AddPoint(3, 3);
Console.WriteLine(geometry1.SpatiallyEquals(geometry2)); // False

Touches

Returns true if two geometries have at lease one common boundary points, but no interior points.
Here is an example:

var geometry1 = new LineString();
geometry1.AddPoint(0, 0);
geometry1.AddPoint(2, 2);

var geometry2 = new LineString();
geometry2.AddPoint(2, 2);
geometry2.AddPoint(3, 3);

Console.WriteLine(geometry1.Touches(geometry2)); // True
Console.WriteLine(geometry2.Touches(geometry1)); // True

var geometry3 = new Point(2, 2);
Console.WriteLine(geometry1.Touches(geometry3)); // True

var geometry4 = new LineString();
geometry4.AddPoint(1, 1);
geometry4.AddPoint(4, 4);

Console.WriteLine(geometry1.Touches(geometry4)); // False

Within

Tests if geometry is contained by another. Equal to SpatiallyContains with this and other geometries swapped.

Methods for generation of derivative geometry

Difference

Returns geometry that is a difference of this geometry and the argument geometry, containing points from this geometry, that are not contained in argument geometry.

GetBuffer

Returns geometry that contains all points within specified distance from this geometry. Useful when you need a 'border area' around geometry.

GetCentroid

Returns geometric center of geometry, in layman terms - point at which cutout of the shape can be perfectly balanced on a pin.

GetConvexHull

Returns convex hull of the geometry. Null if geometry is empty, point if geometry is a point, is it's two points, then line between points, otherwise ILinearRing that is a convex hull around all points.

Intersection

Returns geometry that contains points that are contained in both this geometry and argument geometry.

SymDifference

Returns geometry that contains points that are contained in either this or argument geometry, but not both.

Union

Returns geometry that is a sum of this and argument geometries, containing points from both geometries.

General case relation, DE-9IM model.

The Relate method allows one to specify any desired pattern for DE-9IM intersection matrix. In fact, most of the above relation-deriving methods are wrappers for this method. Method builds DE-9IM matrix for the two geometries and tests if it fits the provided pattern.
Pattern is a string of 9 characters.
Each position represents specific spatial relation:

0 - between interiors of geometries.
1 - between interior of this geometry and boundary of the other.
2 - between interior of this geometry and exterior of the other.
3 - between boundary of this geometry and interor of the other.
4 - between boundaries of the geometries.
5 - between boundary of this geometry and exterior of the other.
6 - between exterior of this geometry and interior of another geometry.
7 - between exterior of this geometry and boundary of another geometry.
8 - between exteriors of the geometries.

Each character can have the following values:

* - any value
F - no intersection
T - any intersection
0 - point intersection (shared point)
1 - line intersection (shared line segment)
2 - surface intersection (shared part of polygon)

For example, an intersection pattern "F0*******" means, that there should not be intersection between geometries interiors and intersection between geometries boundaries must be a point.
Also you can see OpenGIS Simple Features Specification for more details.
Here is an example on how to use it:

var geometry1 = new LineString();
geometry1.AddPoint(0, 0);
geometry1.AddPoint(0, 2);

var geometry2 = new LineString();
geometry2.AddPoint(0, 1);
geometry2.AddPoint(0, 3);

// Relate method takes a string representation of DE-9IM matrix
// (Dimensionally Extended Nine-Intersection Model matrix).
// see Simple Feature Access specification for more details on DE-9IM.

// this is the equivalent of 'geometry1.SpatiallyEquals(geometry2)'
Console.WriteLine(geometry1.Relate(geometry2, "T*F**FFF*")); // False

// this is the equivalent of 'geometry1.Disjoint(geometry2)'
Console.WriteLine(geometry1.Relate(geometry2, "FF*FF****")); // False

// this is the equivalent of 'geometry1.Overlaps(geometry2)'
Console.WriteLine(geometry1.Relate(geometry2, "1*T***T**")); // True

Miscellaneous methods

RoundM

Rounds M coordinate to a specified number of fractional digits.

RoundXY

Rounds X and Y coordinates to a specified number of fractional digits.

RoundZ

Rounds Z coordinate to a specified number of fractional digits.

SetEmpty

Empties the geometry.

Together, these methods allow you to analyse topological relation of geometries, do 'cookie-cutting', compare their areas and a lot more.

That's all for now, stay tuned!

For more examples please visit the Aspose.GIS GitHub page. There's also Twitter and Facebook pages for news on Aspose.GIS.

Recent progress of Aspose.Imaging

Dmitry Matuzko — Mon, 15 Oct 2018 13:12:51 +0000

In this article I'll tell about recent notable improvements of Aspose.Imaging.

Fixed saving Baseline JPEG to Progressive.

Previously, in case you read an baseline JPEG image and tried to export it as progressive JPEG, you'd get an exception. Now this error is fixed and you can do it just fine like that:

using (Image image = Image.Load("interleaved.jpg"))
{
    JpegOptions saveOptions = new JpegOptions();
    saveOptions.CompressionType = JpegCompressionMode.Progressive;

    image.Save(dir + "interleaved_progressive.jpg", saveOptions);
}

Incorrect EMF creation.

Before, graphic primitive count in EMF's header was set incorrectly, leading to incorrect representation of the last added graphic primitive. The error has been fixed and EMFs are created correctly.

Dashed lines saved as solid when exporting to SVG.

When source containing dashed lines was saved to SVG - be it vector graphics file or newly created set of graphic primitives, they were exported to SVG as solid lines. As of Aspose.Imaging 18.9, this problem has been fixed for licensed mode. However, when operating without license, lines still get converted to solid ones. This problem should be resolved in Aspose.Imaging 18.10 release.

JPEG encoder optimisations.

JPEG DCT encoder has been optimised and displays up to 50% more performance (= up to 30% less time to encode).

DICOM losing color when exporting to BMP.

DICOM files with RGB color space that used lossless JPEG compression were exported as grayscale when exporting to BMP (actually, they were read as grayscale). Now this has been fixed and output JPEG should be correct.

That's all for now, stay tuned!

For more examples please visit the Aspose.Imaging GitHub page. There's also Twitter and Facebook pages for news on Aspose.Imaging.

Clarifying layouts, Model and Paper spaces in Aspose.CAD.

Dmitry Matuzko — Mon, 08 Oct 2018 20:46:20 +0000

In AutoCAD workflow, there is concept of separate model and paper spaces. In model space, you create entities as they should physically appear, with real-world dimensions etc. To create an printable drawing, you switch to paper space and create layouts which contain viewports that display different views of model space, and various annotations. Here dimensions correspond to dimensions you'll see in actual paper print. Model space is accessible from Model tab, and paper space is accessible from layout tabs.

How to see my paper space layouts using Aspose.CAD?

Aspose.CAD supports all that, but has a bit different terminology. Both model space and paper space's layouts are called layouts, and model space just has a specific layout name - "Model". To select which layout to export, create an array of layout names (of string type, of course) and set CadRasterizationOptions's instance's Layouts property with that array. Then all specified layouts will be exported at once as different pages, so if you do want to export several layouts at once, use PDF or TIFF as output format. If you specify an single-page output format, only the first specified layout will be exported. See the following example:

using (Aspose.CAD.Image image = Aspose.CAD.Image.Load("source.dwg"))
{
    // Create an instance of CadRasterizationOptions
    Aspose.CAD.ImageOptions.CadRasterizationOptions rasterizationOptions = new Aspose.CAD.ImageOptions.CadRasterizationOptions();

    // Set page width & height
    rasterizationOptions.PageWidth = 1200;
    rasterizationOptions.PageHeight = 1200;

    // Specify a list of layout names
    rasterizationOptions.Layouts = new string[] { "Model", "Layout1" };

    // Create an instance of TiffOptions for the resultant image
    ImageOptionsBase options = new Aspose.CAD.ImageOptions.TiffOptions(Aspose.CAD.FileFormats.Tiff.Enums.TiffExpectedFormat.Default);

    // Set rasterization options
    options.VectorRasterizationOptions = rasterizationOptions;

    // Save resultant image
    image.Save("", options);                
}

As we can see, here we export model space and paper space's "Layout1" layout to two separate pages. By default, Layouts property is null. The actual behaviour during export in that default case will vary somewhat depending on file. In most cases, all layouts will be exported. Empty paper space layouts, however, might not be exported. (And if you specify single-page output format, only the Model space will be exported - as it is first layout by default.) To export specific layouts or force all layouts, you have to specify their names, and for that, you obviously need to know them. Given that, a question arises:

So how do I know my layouts' names?

Thankfully, it is not a problem. CadImage class' instances have a Layouts property, which contains a CadLayoutDictionary, that is just an dictionary with string keys and CadLayout values. This dictionary contains all the layouts that are present in file, including Model layout. CadLayout is used for internal representation of an AutoCAD layout in Aspose.CAD. Keys are corresponding layout's names. Layout names are also accessible via LayoutName property of CadLayout. The following example will print all of file's layouts to console:

using (Aspose.CAD.Image image = Aspose.CAD.Image.Load("source.dwg"))
{
    Aspose.CAD.FileFormats.Cad.CadImage cadImage = (Aspose.CAD.FileFormats.Cad.CadImage)image;

    Aspose.CAD.FileFormats.Cad.CadLayoutDictionary layouts = cadImage.Layouts;
    foreach (Aspose.CAD.FileFormats.Cad.CadObjects.CadLayout layout in layouts.Values)
    {
        //Console output:
        //Model
        //Layout1
        Console.WriteLine(layout.LayoutName); 
    }
}

Now we have everything we need to export layouts as we want.

Exporting all paper space layouts from file.

So we get all layout names, filter "Model" out of them, and then export all remaining layouts:

using (Aspose.CAD.Image image = Aspose.CAD.Image.Load("source.dwg"))
{
    Aspose.CAD.FileFormats.Cad.CadImage cadImage = (Aspose.CAD.FileFormats.Cad.CadImage)image;

    List<string> layoutNames = new List<string>();

    Aspose.CAD.FileFormats.Cad.CadLayoutDictionary layouts = cadImage.Layouts;
    foreach (Aspose.CAD.FileFormats.Cad.CadObjects.CadLayout layout in layouts.Values)
    {
        if (layout.LayoutName != "Model")
            layoutNames.Add(layout.LayoutName);
    }

    Aspose.CAD.ImageOptions.PdfOptions pdfOptions = new Aspose.CAD.ImageOptions.PdfOptions();

    Aspose.CAD.ImageOptions.CadRasterizationOptions cadOptions = new ImageOptions.CadRasterizationOptions();

    cadOptions.PageWidth = 1000;
    cadOptions.PageHeight = 1000;

    cadOptions.Layouts = layoutNames.ToArray();

    pdfOptions.VectorRasterizationOptions = cadOptions;

    cadImage.Save("output.pdf", pdfOptions);
}

Voila, we now have a PDF file, which contains all the paper space layouts from AutoCAD file as separate pages.

That's all for now, stay tuned!

For more examples please visit the Aspose.CAD GitHub page. There's also Twitter and Facebook pages for news on Aspose.CAD.

Introduction to Aspose.GIS

Dmitry Matuzko — Wed, 03 Oct 2018 05:17:24 +0000

Aspose.GIS is a software library for .NET platforms that does all the common tasks related to geospatial data files: it converts between supported data formats, can convert geospatial data between different spatial reference systems, even allowing use of a custom reference system, provides convenient API for reading and editing of geospatial data and its attributes from files and also for creation of geospatial data from scratch. More than that, Aspose.GIS can perform some basic analysis of geospatial data, such as determining intersections and overlaps of geometric entities and validating geospatial data.
Here I will show basic examples on how to use these functions of Aspose.GIS. Later, I will explore these features deeper in separate articles.

Concept of working with Aspose.GIS.

The main concept behind Aspose.GIS is use of a common intermediate representation for geospatial data and its attributes, independend of a particular data format used. This is a natural approach, as all the all GIS file formats represent the same kind of data. For example, a whole set of data from a GIS data file is represented as VectorLayer class instance, which contains GIS features represented as Feature class instances, and so on. (GDB files contain many layers, they will be covered below.) This approach facilitates working with all the supported file formats the same way.

Converting between different geodata formats.

Let's take a look on how you can convert data from one format to another. This operation is exceptionally simple, as there is a special static Convert method in VectorLayer class, which takes input file path, input file format, output file path and output file format. File formats are specifying by selecting a driver for corresponding file format, they are availible as properties of Drivers class. Currently, there are GeoJson, Kml, Shapefile, OsmXml, Gpx, Gml and FileGdb drivers for corresponding file formats. Optionally, you can specify options as an instance of ConversionOptions, which provides control over attribute conversion, destination spatial reference system, and input and destination file format processing. Take a look at example:

public void ConvertFormats()
{
    ConversionOptions options = new ConversionOptions();

    //Convert shapefile to GeoJSON
    VectorLayer.Convert("input.shp", Drivers.Shapefile, "output_out.json", Drivers.GeoJson);

    //Now let's try to change attributes during conversion and specify custom attribute converter
    options.AttributesConverter = new AttributesConverterExample();

    //Convert GeoJSON to shapefile using ConversionOptions with custom converter
    VectorLayer.Convert("input.json", Drivers.GeoJson,
    "ConvertGeoJSONToShapeFileWithAttributeAdjustment_out.shp", Drivers.Shapefile, options);
}

private class AttributesConverterExample : IAttributesConverter
{
    //This will simply be called for every attribute in the input file, allowing you to modify the attribute.
    public void ModifyAttribute(FeatureAttribute attribute)
    {
        switch (attribute.Name)
        {
            case "name":
                attribute.Width = 10;
                break;
            case "age":
                attribute.Width = 3;
                attribute.Precision = 0;
                break;
        }
    }
}

Working with Spatial Reference Systems

Spatial reference systems are represented as instances of SpatialReferenceSystem class, and are also managed via static methods of this class. Common SRS are availible as properties of SpatialReferenceSystem class, you can also create your own either by providing WKT description or by instantiating ProjectedSpatialReferenceSystemParameters class. Take a look at the examples:

Create an instance of SRS from WKT and compare it to an prefefined WGS84 SRS:

            string wkt = @"
GEOGCS[""WGS 84"",
    DATUM[""WGS_1984"",
        SPHEROID[""WGS 84"",6378137,298.257223563,
            AUTHORITY[""EPSG"",""7030""]],
        AUTHORITY[""EPSG"",""6326""]],
    PRIMEM[""Greenwich"",0,
        AUTHORITY[""EPSG"",""8901""]],
    UNIT[""degree"",0.01745329251994328,
        AUTHORITY[""EPSG"",""9122""]],
    AUTHORITY[""EPSG"",""4326""]]
";
            var srs = SpatialReferenceSystem.CreateFromWkt(wkt);
            srs.IsEquivalent(SpatialReferenceSystem.Wgs84); // true

Create an SRS via API and export to WKT

var parameters = new ProjectedSpatialReferenceSystemParameters
{
    Name = "WGS 84 / World Mercator",
    Base = SpatialReferenceSystem.Wgs84,
    ProjectionMethodName = "Mercator_1SP",
    LinearUnit = Unit.Meter,
    XAxis = new Axis("Easting", AxisDirection.East),
    YAxis = new Axis("Northing", AxisDirection.North),
    AxisesOrder = ProjectedAxisesOrder.XY,
};
parameters.AddProjectionParameter("central_meridian", 0);
parameters.AddProjectionParameter("scale_factor", 1);
parameters.AddProjectionParameter("false_easting", 100);
parameters.AddProjectionParameter("false_northing", 100);

var projectedSrs = SpatialReferenceSystem.CreateProjected(parameters, Identifier.Epsg(3395));

string wkt = projectedSrs.ExportToWkt();
Console.WriteLine(wkt);

Check for support of particular SRS in file format

Drivers.Shapefile.SupportsSpatialReferenceSystem(SpatialReferenceSystem.Wgs72); // true
Drivers.GeoJson.SupportsSpatialReferenceSystem(SpatialReferenceSystem.Wgs84); // true
Drivers.GeoJson.SupportsSpatialReferenceSystem(SpatialReferenceSystem.Wgs72); // false

As you can see, working with SRS in Aspose.GIS is straightforward.

Reading features from geodata files

Files are loaded as instances of VectorLayer class. There are two approaches to loading files: either call OpenLayer on a static property of Drivers class that corresponds to your file format, specifying path to file, or call static Open method of VectorLayer class, specifying path to file and a corresponding file format driver (again, via static property of Drivers class). Example here shows first approach.
Geospatial features are availible right by iteration over VectorLayer instance. Geometric data is stored at Geometry property of Feature, and attributes can be read using GetValue<T>() method:

using (var layer = Drivers.OsmXml.OpenLayer(dataDir + "fountain.osm"))
{
    // get feratures count
    int count = layer.Count;

    Console.WriteLine("Layer count: " + count);
    // get feature at index 2
    Feature featureAtIndex2 = layer[2];

    // iterate through all features.
    foreach (Feature feature in layer)
    {
        // handle feature
        Console.WriteLine(feature.Geometry.GeometryType);

        //read attribute and display if it's present
        string data = featureAtIndex2.GetValue<string>("string_data");
        if(data!=null)
            Console.WriteLine(data);
    }
}

Working with multi-layer GDB files

As GDB files contain many layers, they have to be handled differently. They are represented as instances of Dataset class, and loading process is similar to VectorLayer: call static Open method of Dataset providing path to file and file format driver, or instead call OpenDataset method of a Driver. Currently only GDB driver works with Dataset.Open, but it has to be specified for uniformity. Then, separate layers can be picked by using OpenLayerAt method, which takes layer index. Total count of layers is stored in LayersCount property. Layers can also be loaded by name using OpenLayer method.

using (var dataset = Dataset.Open(dataDir + "ThreeLayers.gdb", Drivers.FileGdb))
{
    Console.WriteLine("FileGDB has {0} layers", dataset.LayersCount);
    for (int i = 0; i < dataset.LayersCount; ++i)
    {
        Console.WriteLine("Layer {0} name: {1}", i, dataset.GetLayerName(i));

        using (var layer = dataset.OpenLayerAt(i))
        {
            Console.WriteLine("Layer has {0} features", layer.Count);
            foreach (var feature in layer)
            {
                Console.WriteLine(feature.Geometry);
            }
        }
        Console.WriteLine("");
    }
}

Creating a new geodata file and filling it with data

Creation is done in a way similar to opening an existing file, just using Create() method instead of Open(). After creation, you have an VectorLayer instance that you can add attributes and Feature(s) to. When you dispose the object, changes will be pushed to file.

using (VectorLayer layer = VectorLayer.Create("ShapeFile.shp", Drivers.Shapefile))
{
    // add attributes before adding features
    layer.Attributes.Add(new FeatureAttribute("name", AttributeDataType.String));
    layer.Attributes.Add(new FeatureAttribute("age", AttributeDataType.Integer));
    layer.Attributes.Add(new FeatureAttribute("dob", AttributeDataType.DateTime));

    Feature firstFeature = layer.ConstructFeature();
    firstFeature.Geometry = new Point(33.97, -118.25);
    firstFeature.SetValue("name", "John");
    firstFeature.SetValue("age", 23);
    firstFeature.SetValue("dob", new DateTime(1982, 2,5, 16, 30,0));
    layer.Add(firstFeature);

    Feature secondFeature = layer.ConstructFeature();
    secondFeature.Geometry = new Point(35.81, -96.28);
    secondFeature.SetValue("name", "Mary");
    secondFeature.SetValue("age", 54);
    secondFeature.SetValue("dob", new DateTime(1984, 12, 15, 15, 30, 0));
    layer.Add(secondFeature);
}

Basic analysis: checking for intersections

Geometry class provides instance methods for basic geometry analysis. In this example I'll show use of Intersects() and Disjoint() methods, but there are also other methods.

//Create geometry first.
var geometry1 = new Polygon(new LinearRing(new[]
{
    new Point(0, 0),
    new Point(0, 3),
    new Point(3, 3),
    new Point(3, 0),
    new Point(0, 0),
}));

var geometry2 = new Polygon(new LinearRing(new[]
{
    new Point(1, 1),
    new Point(1, 4),
    new Point(4, 4),
    new Point(4, 1),
    new Point(1, 1),
}));

Console.WriteLine(geometry1.Intersects(geometry2)); // True
Console.WriteLine(geometry2.Intersects(geometry1)); // True

// 'Disjoint' is opposite to 'Intersects'
Console.WriteLine(geometry1.Disjoint(geometry2)); // False

Supported file formats

Aspose.GIS can read and create GeoJSON files, ESRI Shapefiles and File Geodatabases, Keyhole Markup Language (KML) files, OpenStreetMap XML (OSM XML) files, Geography Markup Language (GML) files, and it can also read GPS Exchange Format (GPX) files.

Supported platforms

Aspose.GIS is availible for .NET Framework 4.7 and later, and for .NET Standard 2.0 and later. As such, it works on such platforms as .NET Framework, .NET Core, Mono 5.4 or later, Xamarin.iOS 10.14 or later, Xamarin.Mac 3.8 or later and Xamarin.Android 8.0 or later.

That's all for now, stay tuned!

For more examples please visit the Aspose.GIS GitHub page. There's also Twitter and Facebook pages for news on Aspose.GIS.

Clarifying image creation in Aspose.Imaging

Dmitry Matuzko — Tue, 18 Sep 2018 18:28:43 +0000

As it was stated in previous articles, Aspose.Imaging not only allows loading, manipulation and export of images, but it also allows creation of images from scratch. The creation process, however, might not be very obvious, so I'll describe it here in a few more words.

To create a new image in Aspose.Imaging, use Image's Create method. It accepts three parameters - an instance of a descendant of ImageOptions (i.e. PngOptions, BmpOptions etc.), and width and height in pixels. The ImageOptions' descendant instance is the same that is ordinarily used to export image - as that ImageOptions specifies what's needed for a new image - pixel format, etc. In this case it would just produce clean white file, instead of filling it with content from another image. That's why width and height are specified separately - as exported image's dimensions are inferred from its content, and when creating new image, we have no content yet. Take a look at the example and don't skip the following paragraph!

using (FileStream stream = new FileStream("newImage.png", FileMode.Create))
{
    // So we want to create a PNG image
    PngOptions saveOptions = new PngOptions();
    // Here you can set whatever properties of saveOptions you need

    // Set the Source for PngOptions and create an instance of Image
    saveOptions.Source = new StreamSource(stream);               
    using (Image image = Image.Create(saveOptions, 100, 100))
    {
        // Create and initialize an instance of Graphics class and clear Graphics surface
        Graphics graphic = new Graphics(image);
        graphic.Clear(Color.Yellow);

        // Draw an arc shape by specifying the Pen object having red black color and coordinates, height, width,    start & end angles                 
        int width = 100;
        int height = 200;
        int startAngle = 45;
        int sweepAngle = 270;

        // Draw arc to screen and save all changes.
        graphic.DrawArc(new Pen(Color.Black), 0, 0, width, height, startAngle, sweepAngle);
        // Note you can just call Save() without parameters, as source is bound to image
        image.Save();
    }
    // Now close the stream.
    stream.Close();
}

Note that besides all the typical properties you specify when exporting an image, here we also specify Source property. That's how we specify where the newly created image should be stored and this property must be set with a Source created from a valid writable Stream to create an image.

There is also a helper method that allows you to skip creating Stream by yourself, the FileCreateSource method in the FileCreateSource class. Take a look at using it:

ImageOptions.Source = new FileCreateSource("myNewImage.png", false);

Note the second parameter, it allows creation of temporary files. If you set it to true, the file will be created as temporary one. Nonetheless, you should dispose the stream after you used it.

Note also how we can just apply changes to the image by calling parameterless Save() in the first example - this is exactly because Source is specified and image is bound to a file. This is in contrast to loading an existing image, which is virtually copied and has to be saved to an explicitly provided file.

That's all for now, stay tuned!

For more examples please visit the Aspose.Imaging GitHub page. There's also Twitter and Facebook pages for news on Aspose.Imaging.

Control over rasterization in Aspose.CAD.

Dmitry Matuzko — Thu, 13 Sep 2018 12:02:48 +0000

Aspose.CAD allows some control over rasterization of CAD files to raster images and PDF files. Let's see what's possible with them.

Rasterization itself, in essence, is controlled by an instance of CadRasterizationOptions class, which is assigned to VectorRasterizationOptions property of instance of output format-specific descendant of ImageOptionsBase, i.e. PdfOptions, PngOptions etc. Consequently, when you pass the output options instance to Image's Save method, it's the CadRasterizationOptions property which specifies what will be rendered, and output options themselves only set up the file that contains the rendered image. Here we will focus on the CadRasterizationOptions instead of format-specific options.

PageHeight and PageWidth properties:

obviously, sets output image's height and width. In case of raster image, these define image's dimensions in pixels, in case of PDF, as these are vector images, it is mostly relative and only used for defining output image's aspect ratio, unless UnitType is specified, then these will define actual physical dimensions of PDF page(s), and content will be scaled to fit it.

PageSize:

Is essentially the same, just accepts SizeF which defines height and width at once.

BorderX and BorderY:

These define margins around actual image area, i.e. the final image will have dimensions of PageHeight+BorderX*2 and height of PageWidth+BorderY*2.

CenterDrawing:

If set to true will determine geometric center of displayed objects and pin it to image's center. When exporting 3D entities it will automatically be treated as enabled.

BackgroundColor:

Obviously, sets background color, as CAD systems typically imply there's no background, but you do need one in raster images. Default is white.

DrawColor:

You may override entities' color defined in a CAD document and substitute your own by setting this property to color you want and DrawType property to UseDrawColor. By default, DrawColor is black.

DrawType:

Indicates wether to render entities used colors specified in document, or use DrawColor. Default is UseDrawColor.

UnitType:

Specifies dimension unit of output image. If you're exporting to PDF and have specified output image dimensions, then PDF page will have dimensions of the specified PageHeight and PageWidth in the specified units. If you're exporting to PDF with specified UnitType and without specified dimensions, then PDF's page will have dimensions corresponding to CAD document content, in the specified units. I.e. if an document contains a 100 inch rod, with dimensions specified in inches, and you specify centimeters as UnitType, then output PDF will have an 254 cm rod, with dimensions specified in cm.

In case of raster images, UnitType only matters when output dimensions are not specified. Then one pixel represents 1x1 unit square. So, if you have a feature that's 100 inches wide in document, and you set UnitType to Centimeter and export to raster without specifying dimensions, the feature will have width of 254 pixels. If the CAD image is unitless, image's units are treated as inches.

ContentAsBitmap:

Only applicable when exporting to PDF, if it is set to true, the rendered image will be rasterized and embedded into PDF as raster image, instead of a regular vector one. Default is false.

GraphicsOptions:

Allows to set antialiasing level, interpolation quality and text rendering mode for raster images (including embedded in PDF)

Zoom:

Another way to specify margins. Value of 1 corresponds to exact fit, value below 1 allows to create margins, value above 1 allows to scale drawing up.

PenOptions:

Allows to set pen options for entities with no defined pen options. Currently only allows setting start and end line caps.

ObserverPoint:

Only matters for IFC images, as these do not have defined observation point. By default, observation point is looking "down" along Z axis.

RenderResult:

A handler that will receive CadRenderResult when render will be completed. Allows to see list of errors that have happened during render.

TypeOfEntities:

Specifies either 2D or 3D entities to render for AutoCAD files. Most entities are rendered either way, some are 2D only, some are 3D only, more detailed explaination is in Clarifying export of 3D entities with Aspose.CAD article.

Layers:

Gets or sets layers to export for AutoCAD documents.

Layouts:

Gets or sets layout names to export for AutoCAD documents. If null, Model layout will be exported.

PdfProductLocation:

AutoCAD files may have underlays that refer to PDF files. Aspose.CAD can't render PDF's by itself, so this option is used to specify location of Aspose.PDF DLL file that can read PDF files. License file is expected to be in the same folder.

AutomaticLayoutScaling:

Scales CAD document content to output image size if set to true, default is true.

NoScaling:

Defines wether to scale CAD content to match output image. This is overridden by AutomaticLayoutScaling - if that is set to true, NoScaling will have no effect.

For most file formats, when AutomaticLayoutScaling is false and NoScaling is true, no scaling is done at all, i.e. if your file's contents fit within 5 relative units defined in file, then these contents will be rasterized into 5 pixels, so you won't be able to discern anything if you export to raster. If you export to PDF, correspondingly, you'll have to zoom in to see details.

Exceptions are IFC, which is always scaled to fit, and AutoCAD files, for which, in that case, viewport will be scaled and centered to image's center, instead of actual entities. So, if you're exporting AutoCAD file where entities occupy a small part of viewport and ScaleMethod is set to none, entities will occupy a correspondingly small part of output image, and on the contrary, if scaling is used, these entiites will occupy the whole output image.

That's all for now, stay tuned!

For more examples please visit the Aspose.CAD GitHub page. There's also Twitter and Facebook pages for news on Aspose.CAD.

Clarifying export of 3D entities with Aspose.CAD

Dmitry Matuzko — Tue, 04 Sep 2018 11:35:11 +0000

Aspose.CAD supports export of 3D entities from AutoCAD and STL files. For other formats, there is currently (as of 18.8) no support for 3D entities.

One can specify which entities to export using CadRasterizationOptions's TypeOfEntities property - it's
of TypeOfEntities enum type, accepting either Entities3D or Entities2D (default) value. See the example:

using (Aspose.CAD.Image cadImage = Aspose.CAD.Image.Load("image.dwg"))
{
    Aspose.CAD.ImageOptions.CadRasterizationOptions rasterizationOptions = new
    Aspose.CAD.ImageOptions.CadRasterizationOptions();
    rasterizationOptions.PageWidth = 500;
    rasterizationOptions.PageHeight = 500;
    rasterizationOptions.TypeOfEntities = TypeOfEntities.Entities3D;


    PdfOptions pdfOptions = new PdfOptions();
    pdfOptions.VectorRasterizationOptions = rasterizationOptions;

    cadImage.Save("Export3DImagestoPDF_out.pdf", pdfOptions);
}

For AutoCAD files, most entity types will be exported in both cases, though with some differences due to projection. However, there are entities that are only exported when a corresponding entity type is set.
Entities that are only exported in 2D mode include: attribute and attribute definition entities, underlays, raster images, Table, Text and MText entities. Entities that are only exported in 3D mode include: 3D face and solid entities, mesh entities, plane, swept, extruded and revolved surfaces.
If 3D entities are selected for export, output image will be automatically centered to them - same way as when setting CenterDrawing property of CadRasterizationOptions to true - geometric center of all 3D entities in image is determined and is pinned to output image's center.

For an STL file, you may not specify TypeOfEntities - it will be automatically set to Entities3D, as STL only has 3D entities anyway. Centering happens the same way.

For other file formats, specifying 3D entities for export will only cause centering - this is a default behaviour for all formats.

That's all for now, stay tuned!

For more examples please visit the Aspose.CAD GitHub page. There's also Twitter and Facebook pages for news on Aspose.CAD.

Controlling image loading process in Aspose.Imaging

Dmitry Matuzko — Wed, 22 Aug 2018 08:18:37 +0000

Aspose.Imaging provides options to control image loading process, so as wether to apply ICC profile or not, or how high error tolerance is allowed. Most options are related to PSD format, but some other image formats have their options as well, and there are some options common for all formats.

Using LoadOptions

Specifying options for image loading process is straightforward: create an instance of LoadOptions class or its descendant for corresponding image format, set up its properties and pass it to Image's Load method. The following example disables default behaviour of processing image raster data with image's embedded ICC profile on loading.

LoadOptions loadOptions = new LoadOptions();
loadOptions.UseIccProfileConversion = false;

using(image = Image.load(sourcePath, loadOptions))
{
    image.save(outputPath, new PngOptions());
}

For format-specific options, just create an instance of corresponding class and be sure you're loading an image of that exact format, otherwise it's the same.

Common loading options

Options that are common for all formats are defined in the base LoadOptions class. There is a total of three availible options:
UseIccProfileConversion - Used to force disable or force enable application of image's embedded ICC profile to image's raster data.
DataBackgroundColor - sets the background color. Background color is typically used for damaged data, when original pixel color can't be recovered.
DataRecoveryMode - sets damage tolerance mode. Either throw exception on any error, or try to recover data while it's consistent and format is not broken, or recover without any checking.

PSD options

PSD, being a complex format, has the most options. In addition to common options, PsdLoadOptions adds next options:
DefaultReplacementFont - the font that will be used to draw text during raster export if the font specified in text layer is not present in system.
IgnoreAlphaChannel - if true, discards aplha data.
IgnoreTextLayerWidthOnUpdate - Whether text layer's fixed width will be ignoring when text is updated when you're working with image.
LoadEffectsResource - Whether effect resources should be loaded. Default is false. If the option is set, only supported effects will be applied anyways.
ReadOnlyMode - When read only mode is set, changes applied to layers will not be saved to final image, all data is used straight from ImageData section, so loaded image is identical to Photoshop.
UseDiskForLoadEffectsResource - By default, effect resources are loaded from disk, if you have enough RAM, you can set it so effect resources will be loaded into memory, thus making processing faster.

PNG options

PngLoadOptions adds StrictMode option, which is an additional error tolerance setting that checks if any of file's critical chunks is truncated. As file can be loaded with some chunks missing, default setting is false.

DNG options

DngLoadOptions adds option to control pre-demosaic denoising as Fbdd property. Either no reduction, light reduction or full reduction.

SVG options

SvgLoadOptions adds DefaultHeight and DefaultWidth properties, which set or get the respective dimensions to which the image is rendered. Should only be used when dimensions are not specified in file.

JPEG2000 options

Jpeg2000 is a relatively complex algorithm and thus decoding can be slow. So MaximumDecodingTime option is present in Jpeg2000LoadOptions to prevent hanging on slower machines on very large - over 5500x6500 pixels - images. Time is specified in seconds.

That's all for now, stay tuned!

For more examples please visit the Aspose.Imaging GitHub page. There's also Twitter and Facebook pages for news on Aspose.Imaging.

Working with ICC profiles in Aspose.Imaging

Dmitry Matuzko — Thu, 16 Aug 2018 07:11:13 +0000

Aspose.Imaging supports retrieving, applying and storing ICC color profiles for PSD and JPEG images, and can embed color profiles when exporting TIFF images. For other formats, embedded color profiles are processed when loading image, but are not availible for manipulation as of v18.7. In this article I'll show how to work with ICC profiles for JPEG, PSD and TIFF.

Helper methods for loading and saving profiles

ICC color profiles stored in PSD and JPEG images are represented as properties of type StreamSource, which facilitates directly loading/saving them from/to .icc(m) files.
In this section I will provide methods that will be used in following sections. Here are methods to create a StreamSource from file and to save StreamSource to file:

using Aspose.Imaging.Sources;
using Aspose.Imaging.ImageOptions;
using System.IO;


private static StreamSource GetSourceForFilename(string filename)
{
    MemoryStream memory = new MemoryStream(File.ReadAllBytes(filename));
    memory.Seek(0, System.IO.SeekOrigin.Begin);
    StreamSource source = new StreamSource(memory);
    return source;
}

private static void SaveSourceToFile(StreamSource source, string filename)
{
    using (FileStream fileStream = new FileStream(filename, FileMode.Create))
    {
        long position = source.Stream.Position;
        source.Stream.Seek(0, System.IO.SeekOrigin.Begin);
        int byteCount;
        byte[] buffer = new byte[1024];
        while ((byteCount = source.Stream.Read(buffer, 0, buffer.Length)) > 0)
        {
            fileStream.Write(buffer, 0, byteCount);
        }
        source.Stream.Seek(position, System.IO.SeekOrigin.Begin);
        fileStream.Flush();
    }
}

In case of TIFF files, color profiles are applied during saving of the image, and are provided in IccProfile property of TiffOptions's instance as an instance of MemoryStream. Here are methods to convert StreamSource to MemoryStream and to load a file into MemoryStream:

private static MemoryStream FileToMemoryStream(string filename)
{
    MemoryStream memory = new MemoryStream(File.ReadAllBytes(filename));
    memory.Seek(0, System.IO.SeekOrigin.Begin);
    return memory;
}

        private static MemoryStream SourceToMemoryStream(StreamSource streamSource)
{
    Stream srcStream = streamSource.Stream;
    MemoryStream dstStream = new MemoryStream();

    int byteCount;
    byte[] buffer = new byte[1024];
    long pos = srcStream.Position;
    srcStream.Seek(0, System.IO.SeekOrigin.Begin);
    while ((byteCount = srcStream.Read(buffer, 0, buffer.Length)) > 0)
    {
        dstStream.Write(buffer, 0, byteCount);
    }

    srcStream.Seek(pos, System.IO.SeekOrigin.Begin);
    return dstStream;
}

Applying color profile when saving to TIFF

This is straightforward to do: just set IccProfile property of TiffOptions with the profile, and save the image:

using (Image image = Image.Load("sample.jpg"))
{
    TiffOptions options = new TiffOptions(FileFormats.Tiff.Enums.TiffExpectedFormat.Default);
    using(MemoryStream ms = FileToMemoryStream("profile.icc"))
    {
        options.IccProfile = ms;
        image.Save("profiled_sample.tif", options);
    }
}

Color profiles in PSD

There are three color profile properties in PSDImage, two of them are applied to CMYK images and must be used together for correct conversion, these are the RgbColorProfile and CmykColorProfile. By default, if these profiles are embedded in image, they will be applied during loading by default.
Here is an example where CMYK color profile from PSD image is embedded into CMYK TIFF image:

string inputFile = "cmyk.psd";
string outputFile = "cmyk.tiff";

using (PsdImage image = (PsdImage)Image.Load(inputFile))
{
    TiffOptions tiff = new TiffOptions(FileFormats.Tiff.Enums.TiffExpectedFormat.TiffLzwCmyk);
    using (MemoryStream ms = SourceToMemoryStream(image.CmykColorProfile))
    {
        tiff.IccProfile = ms;
        image.Save(outputFile, tiff);
    }
}

Third is GrayColorProfile, used in monochrome images, and is not applied during loading. To enable application of profile explicitly, create LoadOptions instance, set UseIccProfileConversion to true and load image using this instance. See example:

// Save to grayscale TIFF
TiffOptions saveOptions = new TiffOptions(TiffExpectedFormat.Default);
saveOptions.setPhotometric(TiffPhotometrics.MinIsBlack);
saveOptions.setBitsPerSample(new int[] { 8 });

// If the image contains a built-in Gray ICC profile, it is not be applied by default in contrast of the CMYK profile.
// Enable ICC conversion explicitly.
LoadOptions loadOptions = new LoadOptions();
loadOptions.UseIccProfileConversion= true;

using(PsdImage psdImage = (PsdImage)Image.load(sourcePath, loadOptions))
{
    // Embed the gray ICC profile to the output TIFF.
    // The built-in Gray Profile can be read via the PsdImage.GrayColorProfile property.
    saveOptions.setIccProfile(toMemoryStream(psdImage.getGrayColorProfile()));
    psdImage.save(outputPath, saveOptions);
}

Color profiles in JPEG

JpegImage contains four properties related to color profiles. RgbColorProfile and CmykColorProfile, likewise to PSD, are used for CMYK and YCCK JPEG images when loading the image. DestinationCmykColorProfile and DestinationRgbColorProfile are applied when a JpegImage is saved, and should be paired with opponent profile - i.e. when using DestinationCmykColorProfile, RgbColorProfile should be set to a corresponding profile, and when using DestinationRgbColorProfile, CmykColorProfile should be set to a corresponding profile too.
Here is an example that shows use of profiles when loading image:

using (JpegImage image = (JpegImage)Image.Load("image.jpg"))
{
    //load profiles
    StreamSource rgbprofile = GetSourceForFilename("rgb.icc");
    StreamSource cmykprofile = GetSourceForFilename("cmyk.icc");
    // set profiles for image
    image.RgbColorProfile = rgbprofile;
    image.CmykColorProfile = cmykprofile;
    //now the profiles are applied when image's data is retrieved
    Aspose.Imaging.Color[] colors = image.LoadPixels(new Rectangle(0, 0, image.Width, image.Height));
}

Here is an example that shows use of profiles when saving image:

using (JpegImage image = (JpegImage)Image.Load("image.jpg"))
{
    //load profiles
    StreamSource rgbprofile = GetSourceForFilename("rgb.icc");
    StreamSource cmykprofile = GetSourceForFilename("cmyk.icc");
    // apply profiles to image for saving
    image.DestinationRgbColorProfile = rgbprofile;
    image.DestinationCmykColorProfile = cmykprofile;
    //save changes back to image
    image.Save();
}

Disabling default application of embedded color profile.

If you don't want to apply image's embedded color profile during image loading, there is an option to disable this processing using LoadOptions. See example:

LoadOptions loadOptions = new LoadOptions();
loadOptions.UseIccProfileConversion= false;

using(image = Image.load(sourcePath, loadOptions))
{
    image.save(outputPath, new PngOptions());
}

That's all for now, stay tuned!

For more examples please visit the Aspose.Imaging GitHub page. There's also Twitter and Facebook pages for news on Aspose.Imaging.