Frequently Asked Questions

By default, XPSConvert saves converted files in the current working folder. To specify another output location, use the '-o' (or --output) parameter. For example:

xpsconvert --o "c:\My Output" 1.xps 2.xps 3.xps

Note: If the specified path does not exist, XPSConvert will attempt to create the necessary folders.

When converting to PDF, XPSConvert will, by default, create a single file with the name of the input XPS file. The output filename can be changed using the '--prefix' option. For example, the following command-line generates an output document named outdoc.pdf:

xpsconvert --prefix outdoc mydoc.xps

The default behavior for image conversion is to create a separate image file for every page in the document. The output filename is constructed using the name of the input XPS file, page counter, and appropriate image extension. For example, the following command-line generates a sequence of image files starting with mydoc_1.jpg, mydoc_2.jpg, etc.:

xpsconvert -f jpg mydoc.xps

XPSConvert allows output filename customizations using the '--prefix' and '--digits' options. For example, the following command-line generates a sequence of image files starting with newname_0001.jpg, newname_0002.jpg, etc.:

xpsconvert -f jpg --prefix newname --digits 4 mydoc.xps

The '--digits' parameter specifies the number of digits used in the page counter portion of the output filename. By default, new digits are added as needed, however this parameter could be used to format the page counter field to a uniform width (e.g. myfile_0001.jpg, myfile_0010.jpg, instead of myfile_1.jpg, myfile_10.jpg, etc).

If your output image format is TIFF, you can convert XPS to a single, multi-page TIFF document using the '--multipage' option (See 'How do I convert XPS to multi-page TIF?' for an example).

To avoid any ambiguities in file naming, the prefix option should be used only for conversion of individual documents.

By default, XPSConvert automatically converts XPS to PDF. The output format can be modified using the '-f' (or --format) option. For example,

xpsconvert -f jpg in.xps

will convert XPS to JPEG.

The '--format' parameter accepts any of the following output formats:

• pdf -- (Portable Document Format)
• png - (Portable Network Graphics)
• png8 -- (Palletized PNG)
• jpg or jpeg (Joint Photographic Expert Group)
• tif or tiff (Tagged Image File Format)
• tif8 -- (Palletized TIFF)
• bmp (Windows Bitmap Format)
• raw (raw RGB or Gray data)

By default, XPSConvert will convert all XPS pages to the output format. You can specify a subset of pages to convert using the '-a' or '--pages' options. For example:

xpsconvert -a 1,3,10 in.xps

will convert only pages 1, 3, and 10. Please note that XPSConvert assumes that all pages are numbered sequentially starting from page 1.

To specify a range of pages, use dash character between numbers. For example:

xpsconvert -a 1,10-20,50- in.xps

will render the first page, pages in the range from 10 to 20 and all pages starting with page 50 to the last page in the document.

All even pages can be selected using the 'e' (or 'even') string. For example, the following line renders all even pages:

xpsconvert --pages even in.xps

Similarly odd pages can be selected using the 'o' (or 'odd') string. The following line renders all odd pages in the document and every page in the range from 100 to the last page:

xpsconvert --pages odd,100- in.xps

The resulting rotation can be modified using the '-r' (or --rotate) option. For example, the following line rotates all pages 90 degrees counterclockwise:

xpsconvert --rotate 90 Test/tiger.xps

Similarly, the following line rotates the page 270 degrees counterclockwise (or 90 degrees clockwise):

xpsconvert --rotate 270 Test/tiger.xps

By default, XPSConvert will convert XPS files if they are in zip format. You can convert directories in XPS format by using the option --physical-model. For Example:

xpsconvert --physical_model dir xps_dir

In this example 'xps_dir' could be created by unzipping an XPS file. This directory would contain files with XML markup and other XPS resources.

The "--physical_model" parameter accepts any of the following output formats:

• zip (xps parts contained in a zip archive)
• dir (xps parts contained in a directory)
• all (processes both zip files and xps directories)

XPSConvert supports batch conversion of many PDF files in a single pass. To convert all PDF files in a given folder(s) you can use the following syntax:

xpsconvert myfolder1

The '--subfolders' option can be used to recursively process all subfolders. For example, the following line will convert all documents in 'myfolder1' and 'myfolder2' as well as all subfolders:

xpsconvert --subfolders myfolder1 myfolder2

By default, XPSConvert will convert all files with the extension '.xps'. To select different files based on the extension use the '--extension' parameter. For example, to convert all XPS documents with a custom extension '.blob', you could use the following line:

xpsconvert --extension .blob --subfolders myfolder1

The use of wild characters is also allowed. For example, to convert all XPS files starting with 'x' in the current folder use:

xpsconvert x*.xps

If your output format is TIFF, you can convert XPS to a single, multi-page TIFF document instead of a separate file for every page using the '--multipage' option.

For example:

xpsconvert --multipage -f tif --verb 3 myxps.xps

By default, XPSConvert uses the RGB color model for rasterization and image export. You can instruct XPSConvert to use single channel Device Gray color model for rasterization and image export using the '--gray' option. For example:

xpsconvert -f tiff --gray in.xps

Using XPSConvert output image resolution can be specified explicitly (using the '--d' or '--dpi' option) or implicitly (using the '--hres' and '--vres' parameters). In this section, we cover the use of the '--dpi' parameter. For more information on the '--hres' and '--vres' parameters, see 'How do I specify dimensions of the output image in pixels?'

By default, XPSConvert uses resolution of 92 Dots Per Inch (DPI), which is the typical screen resolution. Smaller DPI numbers result in smaller images (e.g. suitable for use as thumbnails), while larger DPI numbers generate larger images (e.g. suitable for high-quality output).

For example, to convert a XPS document to a multi-page TIF at 300 DPI (Dots Per Inch), use the following line:

xpsconvert -f tif --multipage --dpi 300 in.xps

Depending on the dimensions of the input page, high DPI/resolution rasterization requires lots of memory. For example, rasterization of a single A4 page (8x11) at 1000 DPI will require more than 350MB of memory. If XPSConvert fails to allocate enough memory, you can render the image in stripes or tiles, as described in 'How do I render high-resolution images', or by trying to decrease DPI value.

A 'typical' range of acceptable DPI values is between 1 and 1000 DPI. XPSConvert can rasterize images beyond 1000 or 2000 DPI using tiled or striped rendering.

To specify absolute dimensions of the output image in pixels, use the '--hres' and '--vres' parameters.

When these parameters are specified, XPSConvert will automatically determine the DPI (Dots Per Inch) ratio required to match the pixel dimensions of the output image.

For example, to generate 100 by 100 pixels thumbnails for a given XPS, you can use the following line:

xpsconvert -f jpg --hres 100 --vres 100 in.xps

Because the input XPS page may not perfectly fit the absolute pixel size of the output image, XPSConvert will also center the page and preserve the aspect ratio during rendering.

To generate images that are proportional in their size to the input XPS pages, simply omit one of the parameters (either --hres or --vres). For example,

xpsconvert -f jpg --hres 100 in.xps

will convert all XPS pages to images that are 100 pixels wide, with height proportional to the dimensions of the input page.

Similarly, the following line will create images with fixed height (100 pixels) and variable width (to preserve the aspect ratio).

xpsconvert -f jpg --vres 100 in.xps

Using XPSConvert you can rasterize a subset of a page using the '--clip' parameter. The parameter accepts a list of four numbers, separated using commas, giving the coordinates of a pair of diagonally opposite corners. Typically, the list takes the form: llx, lly, urx, ury specifying the lower-left x, lower-left y, upper-right x, and upper-right y coordinates of the rectangle, in that order. The other two corners of the rectangle are then assumed to have coordinates (llx, ury) and (urx, lly). All coordinates need to be expressed in points (a basic unit of PDF 'user' coordinate system). One PDF point is 1⁄72 of an inch and is approximately the same as a point (unit commonly used in the printing industry).

The '--clip' parameter is not only useful for cropping pages, but it can be also used to speed up the rendering process and to reduce memory consumption (see 'How to I render very large images?' for details).

XPSConvert also supports clipping to predefined page regions, such as page media, crop, trim, bleed, and art box. For more information on clipping to predefined regions, see 'How can I show/hide crop marks or the trim region?

Depending on the dimensions of the input page, high DPI/resolution rasterization requires lots of memory. For example, rasterization of a single A4 page (8x11) at 1000 DPI will require more than 350MB of memory. If XPSConvert fails to allocate enough memory (a single contiguous block of memory), you can render the image in stripes or tiles by repeatedly rendering different regions of the page using the '--clip' parameter (also see 'How do I render only a subset of a given page?').

For example, if the input page has a media box 0,0,595,842, you could render the page at 2000 DPI (Dots Per Inch) in four stripes (using 210.5 point increments along the Y axis) as follows:

xpsconvert --dpi 2000 --clip 0,0,595,210.5 --prefix t01 Test/tiger.xps

xpsconvert --dpi 2000 --clip 0,210.5,595,421 --prefix t02 Test/tiger.xps

xpsconvert --dpi 2000 --clip 0,421,595,631.5 --prefix t03 Test/tiger.xps

xpsconvert --dpi 2000 --clip 0,631.5,595,842 --prefix t04 Test/tiger.xps

Rendering of the same image in a single pass would require more than 1.4 GB in memory.

The JPEG image format offers a lossy type of compression and the option to trade between the loss in image quality and compression ratio. To fine-tune JPEG compression quality, use the '--quality' parameter as illustrated in the following sample:

xpsconvert --quality 80 -f jpg Test/tiger.xps

Compression quality is a number in the range from 1 to 100. Lower numbers usually result in better compression at the expense of image quality. The default is 80.

To render the XPS as a monochrome (1 bit per pixel) image compressed using G4 CCITT, simply add the option '--mono' within the command-line string. For example,

xpsconvert --mono -f TIFF --verb 10 --dpi 300 in.xps

To enable dithering (grayscale color simulation) add '--dither' option to the command line string.

XPSConvert can be used to for XAML to PDF conversion. To convert XAML to PDF, first serialize flow document as XPS using specific styling information (e.g. page dimensions, header, footer, margins, etc), then pass the output to XPSConvert XPS to PDF conversion function.

In an application that uses Windows Presentation Foundation (WPD), writing the application's data as an XPS Document is straightforward. Windows Presentation Foundation applications describe their graphical content using Extensible Application Markup Language (XAML) code. XPS Documents use a subset of this code as their markup. A WPF application can create an XPS document by calling a method that flattens the application XAML elements of the page into to the XPS page markup.

A managed code application can also create the individual parts of an XPS Document by using the XPS Document API in the System.Windows.Xps.Serialization namespace. This may be a better option for retaining precise control over how the XPS Document is constructed or for adding additional metadata to the document. An application can also create an XPS Document directly, even if the application was not built using Windows Presentation Foundation. This can be done by creating the markup for the individual XPS Document parts, but the classes and methods described here that actually create the XPS Document only run in a managed code environment.

The XamlStreamToXps method from the sample code shown below can enable your WPF application to create an XPS Document. XamlStreamToXps accepts as its arguments the file name of the XPS Document to be created and a Stream containing XAML, which describes the document. XamlStreamToXps will read the input stream and create an XPS Document.

1void XamlStreamToXps(Stream srcXamlStream, ParserContext context, string destXpsFile)
2{
3  XpsDocument document = new XpsDocument(destXpsFile, FileAccess.ReadWrite);
4  XpsPackagingPolicy packagePolicy = new XpsPackagingPolicy(document);
5  XpsSerializationManager serializationMgr = new XpsSerializationManager(packagePolicy, false);
6  object parsedDocObject = (null == context) ? XamlReader.Load (srcXamlStream) : XamlReader.Load (srcXamlStream, context);
7  serializationMgr.SaveAsXaml(parsedDocObject);
8  document.Close();
9}
10
11void XamlFileToXps(string srcXamlFile, string destXpsFile)
12{
13  using(Stream fileStream = File.OpenRead(srcXamlFile))
14  {
15    ParserContext context = new ParserContext();
16    context.BaseUri = new Uri(Directory.GetCurrentDirectory() + \"//\");
17    XamlStreamToXps(fileStream, context, destXpsFile);
18  }
19}

While the default conversion from XAML to XPS is very easy to use, if you want more features, you need to write some code. For full code samples and discussion on how to serialize XAML to XPS, you may want to refer to the following resources:

http://msdn.microsoft.com/en-us/magazine/cc163664.aspx

Please visit Apryse Knowledge Base forum for additional help.

To render the XPS as a CMYK TIFF, simply add the option '--cmyk' or '-k' within the command-line string. For example:

xpsconvert --cmyk -f TIFF --dpi 300 in.xps

For developers who are looking for a software development component to integrate into their application, Apryse also offers a PDF SDK, an easy-to-use, yet powerful software component for embedding into client and server based applications. Our PDF SDK is available as a shared library and can be easily accessed from any programming language (including C#, VB.NET, C/C++, Java, VB6, Perl, Python, Ruby, Delphi, etc). XPSConvert is also available as an add-on module to our PDF SDK.

XPSConvert is a completely stand-alone application and does not include any dependencies on third-party components or software.