Defining shapes

Working with shapes means using the "Create and apply shapes" fixup. pdfToolbox 9 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"

Create new fixup

Create new fixup

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

Setting up new fixup as "Create and apply shapes" fixup
  1. enter "shape" 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

"Create shape" parameter

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

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

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: MediaBox, CropBox, BleedBox, TrimBox, ArtBox (Copy) (Copy)

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

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: MediaBox, CropBox, BleedBox, TrimBox, ArtBox (Copy) (Copy) (Copy)

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

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 die-line colored in a specific spot color.

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

"Shape intent" parameter

"Shape intent" parameter

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

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

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

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

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.

  1. 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.

  1. 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)

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 ver the tracing as such.

Important: The default settings 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
  2. Whether to consider rendered values above this value as transparent
  3. Apply despeckling no more than this number of pixels are of the same color and are surrounded on all sides by pixels of the other 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.
  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.
  7. 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

Shapes based on a custom defined box

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

  1. 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

Shapes based on existing vector paths

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

  1. 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

Parameters for shapes based on existing vector paths

For creation of shapes "From vector paths", only one parameter can be configured: a filter determining which of the vector objects on the respective page to use.

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 die-line colored in a specific spot color.

2 Comments

Jeff

I'm trying to have Callas honor the soft cropping performed in Acrobat and eliminate all content outside of the cropped area in the final pdf. Will this fixup do that?

David van Driessche

Hi Jeff,

I'm not entirely sure what you mean by "honouring soft cropping" but I'm assuming you want to remove content outside of the crop box for example. The shapes fixup will only crop in the same way as Acrobat; it will apply a clipping path which makes the objects outside of it invisible but they will still be there.

You can build a fixup in pdfToolbox to remove all objects outside of the crop box (or any other page box) and there is a fixup to remove parts of images that have been clipped away or are outside of a page box. Those two would be better ways to do what I think you want to do.

If you want more information, drop an email to support@callassoftware.com and we'll help you further.

Take care,
David.

Send Your Comment

E-Mail me when someone replies to this comment