Defining shapes

Working with shapes means using the "Create and apply shapes" Fixup. pdfToolbox comes with a small set of predefined "Create and apply shapes" Fixups, which can be found in the "Shapes, Variables, JavaScript, Place content" Library. The content below will explain how to create custom "Create and apply shapes" Fixups - specifically, how to configure the part that creates shapes. Applying actions to shapes will be explained in the next article.

Creating a Shapes Fixup

In order to create a new Shapes Fixup, simply create a new Fixup, search for "Create and apply shapes" under "Type of Fixup" and select "Create and apply shapes"

Setting up new Fixup as "Create and apply shapes" Fixup

Desktop
  1. Enter "shape" (or just "sha") in the search field
  2. Select the "Create and apply shapes" entry in the "Type of Fixup" list
  3. Use the options under "Create shapes" the configure how shapes are to be created

"Create shape" parameter

Desktop

There are a number of approaches how one or several shapes can be created. The steps below will discuss each (group of) such approaches.

Discussion of the "Create shape: parameters: MediaBox, CropBox, BleedBox, TrimBox, ArtBox

The simplest approach is to pick up a page geometry box (i.e. one of MediaBox, CropBox, BleedBox, TrimBox or ArtBox). Further below you will find a discussion how to fine tune the use of such a page geometry box.

Discussion of the "Create shape: parameters: From tracing page content

A more advanced approach is to use the rendered appearance of page content and create an outline around it (and for any 'holes' inside it). Depending on whether white areas (as opposed to areas that just look white because they are actually transparent and let the white background shine through) are considered part of the rendered page content or not, it is necessary to choose between "From tracing page content (including white areas)" and "From tracing page content (excluding white areas)".

Please see below for a discussion of how to adjust parameters for tracing page content.

Discussion of the "Create shape: parameters: From custom box

This approach is similar to the "From MediaBox" etc. approaches but instead of picking up the existing page geometry box, it is necessary to provide the coordinates of the desired box and its position on the page. Please see below for a discussion of the necessary parameters.

Discussion of the "Create shape: parameters: From vector paths

Another way to derive shapes from page content is to use "From vector paths". This will simply pick up existing path objects (and by implication it does not pick up images, image masks, font based text objects, soft masks, or smooth shades) and turn them into shapes.

Important:

Usually it does not make sense to pick up all path objects on the page, but rather only a small set of path objects, or even just exactly one path object – e.g. a dieline colored in a specific spot color.

Please see below for discussion of how to use parameters for this approach.

Discussion of the "Create shape: parameters: From print surface (Processing Steps: Packaging)

The last way to derive shapes from page content is to use "From print surface" using processing steps information.

"Print surface" is defined in the Processing Steps ISO standard as being the first possible of:

  1. The area contained by all contours specifying the bleed area (i.e. within all Structural/Bleed processing step OCGs) on the PDF page) if present.
  2. The area contained by all contours specifying the die line area (i.e. within all Structural/Cutting processing step OCGs on the PDF page) if present.
  3. The BleedBox of the PDF Page, if present.
  4. The TrimBox of the PDF Page, if present
  5. The ArtBox of the PDF page, if present.
  6. The CropBox of the PDF page, if present
  7. The MediaBox of the PDF Page

"Shape intent" parameter

Desktop

Shapes can be put to use in a number of ways. While aspects such as how to color the area inside a shape or how to stroke its contour are discussed in the next article about applying shapes, some control over the use of each of the individual shapes is already provided in this "Create shape" article.

Discussion of the "Shape intent" parameter: Render only inside shape

Where shapes are to be used for filling the area inside them with a certain color, this would be the option to choose. It is important though to understand that where shapes are inside one another, the even odd rule for painting applies – i.e. if a shape consists of two circles where one circle is completely inside the other circle, only the area between the contours of the two circles will be colored, the areas outside the outer circle and the area inside the inner circle would remain uncolored.

Discussion of the "Shape intent" parameter: Render only outside shape

Where shapes are to be used for filling the outside of an area, but not the area inside it, with a certain color, this would be the option to choose. It is important though to understand that where shapes are inside one another, the even odd rule for painting applies. I.e. in this case if a shape consists of two circles where one circle is completely inside the other circle,  the area between the contours of the two circles will not be colored, but the areas outside the outer circle and the area inside the inner circle would be colored.

Discussion of the "Shape intent" parameter: Suppress rendering inside shape

This shape intent ensures that regardless of any of the other shapes and their shape intent the inner area defined by this shape will remain uncolored. This will normally only make sense if this shape is combined with at least one other shape, that creates a colored (or stroked) area.

Discussion of the "Shape intent" parameter: Suppress rendering outside shape

This shape intent ensures that regardless of any of the other shapes and their shape intent the outside area defined by this shape will remain uncolored. This will normally only make sense if this shape is combined with at least one other shape, that creates a colored (or stroked) area.

Additional parameters for defining shapes

Additional parameters for defining shapes

The third setting "Parameter" in a shape configuration depends on the actual "Create shape" setting, and will differ substantially between them. The steps below explain the parameters for each of the "Create shape" settings.

Shapes based on MediaBox, CropBox, BleedBox, TrimBox, ArtBox

Shapes based on MediaBox, CropBox, BleedBox, TrimBox, ArtBox

When the "Create shape" setting is set to any of the page geometry boxes (in this example it is set to "From TrimBox"), the current "Parameter" values are reported.

Clicking on the "Edit" button, the "Create shape parameters" dialog will open, offering the applicable parameters for editing.

Parameters for shapes based on MediaBox, CropBox, BleedBox, TrimBox, ArtBox

Parameters for shapes based on MediaBox, CropBox, BleedBox, TrimBox, ArtBox
  1. Adjust size makes it possible to subtract from (negative numbers) or to add (positive numbers) to the page geometry box. For example, entering "-5" will make the resulting rectangular shape smaller by 5 units on each side of the rectangle.
  2. "Adjust size unit" makes it possible to pick between point, millimeter and inch.
  3. Where it is desired to create a rectangular shape with rounded corners, a number greater than zero needs to be entered in this field. The number defines the radius of the rounded corners.
  4. "Rounded corner unit" makes it possible to pick between point, millimeter and inch.

Shapes based on tracing page content (including or excluding white areas)

Shapes based on tracing page content (including or excluding white areas)

When the "Create shape" setting is set to one of the two "From tracing page content" options  (in this example it is set to "From tracing page content (excluding white areas)"), the current "Parameter" values are reported.

Clicking on the "Edit" button, the "Create shape parameters" dialog will open, offering the applicable parameters for editing.

Parameters for shapes based on tracing page content (including or excluding white areas)

The parameters in this dialog provide some control over the rendering of the page for tracing purposes, and for the tracing as such.

Important: The default settings for "Despeckle", "Curve smoothness" and "Max. curve optimization error" are the result of extensive research, and are considered to be highly suitable for most use cases. Only in the rare case, where there is reason to assume modified values for these parameters will provide more suitable results, should the values be modified.

  1. Resolution of the (internally rendered) page image
    Value between 36 and 3200, default: 1200; Recommended values: 300 - 1200 ppi
  2. Set threshold for lightness: Value between 0.0 to 1
    0.0: fully opaque, partially transparent objects are ignored;
    1.0: fully transparent, amounts to the whole page area;
    Recommended max. value: 0.99, capture all objects, but not areas where no object is rendered.
  3. Apply despeckling no more than for this number of pixels that are of the same color and are surrounded on all sides by pixels of another color.
  4. Determines the "curve smoothness" to achieved.
    A value of zero would lead to a tracing result where the sides of each pixel of the rendered image are followed precisely, leading to a jaggy tracing result (though at 1200 ppi) the jagginess might not be readily noticeable – nonetheless, this lack of smoothness will increase time to process, and will not add any actual quality to the tracing result.
    0.0: polygons only, no curves;
    1.3334: curves only, no corners;
    Recommended value: 1.0
  5. Makes it possible to enable or disable curve optimization (see 6.)
  6. Maximum delta allowed between a pixel perfect tracing result and the result of curve optimization. A value 0.2 will keep the optimization error at a minimum that will hardly ever be noticeable while still allowing for creation of efficient curves. Values greater than 1 are typically not useful.
  7. Adjust size
  8. Adjust size unit
  9. Makes it possible to create a rendered page only based on the objects found by this filter. For example, if the intention is to create a shape over all vector text objects of spot color "Orange", but not over the rest of the page content, a filter "Is text object using spot color 'Orange'" could be configured and selected, and tracing would happen based on a rendering of the page where the page (temporarily) only shows orange text.

Shapes based on a custom defined box

When the "Create shape" setting is set to "From custom box", the current "Parameter" values are reported.

Clicking on the "Edit" button, the "Create shape parameters" dialog will open, offering the applicable parameters for editing.

Parameters for shapes based on a custom defined box

Parameters for shapes based on a custom defined box

The parameters for "From custom box" are a combination of the parameters for page geometry boxes, and the parameters needed to describe the size and position of the custom page on the page area:

  1. Determines the reference point (relative to the reference rectangle under 2.) starting from which the custom box shall be positioned
  2. Determines the reference rectangle from which the custom box shall be positioned
  3. Horizontal offset from the reference point where the respective corner of the custom box shall be (e.g. for "Lower right corner" of "CropBox" a positive value would move the lower right corner of the custom box to the right)
  4. Vertical offset from the reference point where the respective corner of the custom box shall be (e.g. for "Lower right corner" of "CropBox" a positive value would move the lower right corner of the custom box downwards)
  5. Width of the custom box
  6. Height of  the custom box
  7. Measurement unit for the values entered in fields 3. through 6.
  8. Adjust size makes it possible to subtract from (negative numbers) or to add (positive numbers) to the page geometry box. For example, entering "-5" will make the resulting rectangular shape smaller by 5 units on each side of the rectangle.
  9. "Adjust size unit" makes it possible to pick between point, millimeter and inch.
  10. Where it is desired to create a rectangular shape with rounded corners, a number greater than zero needs to be entered in this field. The number defines the radius of the rounded corners.
  11. "Rounded corner unit" makes it possible to pick between point, millimeter and inch.
  12. Makes it possible to limit the creation (and application) of this shape only t pages where the applicable filter applies. For example, if the filter is set to find objects using a spot  color "Lime Green", only for pages that contain at least one object using that spot color will trigger the creation of this custom box.

Shapes based on existing vector paths

When the "Create shape" setting is set to "From vector paths", the current "Parameter" values are reported.

Clicking on the "Edit" button, the "Create shape parameters" dialog will open, offering the applicable parameters for editing.

Parameters for shapes based on existing vector paths

For creation of shapes "From vector paths", a couple of parameters can be configured: a filter determining which of the vector objects on the respective page to use and adjusting the size.

Shapes based on print surface

When the "Create shape" setting is set to "From print surface", the current "Parameter" values are reported.

Clicking on the "Edit" button, the "Create shape parameters" dialog will open, offering the applicable parameters for editing.

Parameters for shapes based on print surface

For creation of shapes "From print surface", a couple of parameters can be configured:

  1. Adjust size makes it possible to subtract from (negative numbers) or to add (positive numbers) to the page geometry box. For example, entering "-5" will make the resulting rectangular shape smaller by 5 units on each side of the rectangle.
  2. "Adjust size unit" makes it possible to pick between point, millimeter and inch.
  3. Where it is desired to create a rectangular shape with rounded corners, a number greater than zero needs to be entered in this field. The number defines the radius of the rounded corners.
  4. "Rounded corner unit" makes it possible to pick between point, millimeter and inch.

Select pages for which shapes are to be created

Beginning with pdfToolbox 14 it is possible to specify a page filter (based on a Check), so that shapes will only be created on selected pages.

Desktop