Working with Operators

Introduction to the PDF Operators and Their Usage

An operator is a PDF keyword specifying some action that shall be performed, such as painting a graphical shape on the page. An operator keyword is distinguished from a named object by the absence of an initial solidus character (2Fh). Operators are meaningful only inside the content stream.

A content stream is a PDF stream object whose data consists of instructions describing the graphical elements to be painted on a page. More details about PDF operators can be found in the PDF specification.

Implementation details

This topic explains how to use operators with Aspose.PDF. The selected example adds an image into a PDF file to illustrate the concept. To add an image in a PDF file, different operators are needed. This example uses GSave, ConcatenateMatrix, Do, and GRestore.

  • The GSave operator saves the PDF’s current graphical state.
  • The ConcatenateMatrix (concatenate matrix) operator is used to define how an image should be placed on the PDF page.
  • The Do operator draws the image on the page.
  • The GRestore operator restores the graphical state.

To add an image into a PDF file:

  1. Create a Document object and open the input PDF document.
  2. Get the particular page the image is going to be added to.
  3. Add the image into the page’s Resources collection.
  4. Use the operators to place the image on the page:
    • First, use the GSave operator to save the current graphical state.
    • Then use the ConcatenateMatrix operator to specify where the image is to be placed.
    • Use the Do operator to draw the image on the page.
  5. Finally, use GRestore operator to save the updated graphical state.

The following code snippet also work with Aspose.PDF.Drawing library.

The following code snippet shows how to use PDF operators.

// For complete examples and data files, please go to https://github.com/aspose-pdf/Aspose.PDF-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_AsposePdf_Operators();

// Open document
Document document = new Document(dataDir +  "PDFOperators.pdf");

// Set coordinates
int lowerLeftX = 100;
int lowerLeftY = 100;
int upperRightX = 200;
int upperRightY = 200;

// Get the page where image needs to be added
Page page = document.Pages[1];
// Load image into stream
FileStream imageStream = new FileStream(dataDir + "PDFOperators.jpg", FileMode.Open);
// Add image to Images collection of Page Resources
page.Resources.Images.Add(imageStream);
// Using GSave operator: this operator saves current graphics state
page.Contents.Add(new Operators.GSave());
// Create Rectangle and Matrix objects
Aspose.Pdf.Rectangle rectangle = new Aspose.Pdf.Rectangle(lowerLeftX, lowerLeftY, upperRightX, upperRightY);
Matrix matrix = new Matrix(new double[] { rectangle.URX - rectangle.LLX, 0, 0, rectangle.URY - rectangle.LLY, rectangle.LLX, rectangle.LLY });
// Using ConcatenateMatrix (concatenate matrix) operator: defines how image must be placed
page.Contents.Add(new Operators.ConcatenateMatrix(matrix));
XImage ximage = page.Resources.Images[page.Resources.Images.Count];
// Using Do operator: this operator draws image
page.Contents.Add(new Operators.Do(ximage.Name));
// Using GRestore operator: this operator restores graphics state
page.Contents.Add(new Operators.GRestore());
// Save updated document
document.Save(dataDir + "PDFOperators_out.pdf");

Draw XForm on Page using Operators

This topic demonstrates how to use the GSave/GRestore operators, the ContatenateMatrix operator to position an xForm and the Do operator to draw an xForm on a page.

The code below wraps a PDF file’s existing contents with the GSave/GRestore operator pair. This approach helps get the initial graphics state at the and of the existing contents. Without this approach, undesirable transformations might remain at the end of the existing operator chain.

// For complete examples and data files, please go to https://github.com/aspose-pdf/Aspose.PDF-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_AsposePdf_Operators();


string imageFile = dataDir +  "aspose-logo.jpg";
string inFile = dataDir + "DrawXFormOnPage.pdf";
string outFile = dataDir + "blank-sample2_out.pdf";

using (Document document = new Document(inFile))
{
    OperatorCollection pageContents = document.Pages[1].Contents;

    // The sample demonstrates
    // GSave/GRestore operators usage
    // ContatenateMatrix operator usage to position xForm
    // Do operator usage to draw xForm on page

    // Wrap existing contents with GSave/GRestore operators pair
    //        this is to get initial graphics state at the and of existing contents
    //        otherwise there might remain some undesirable transformations at the end of existing operators chain
    pageContents.Insert(1, new Operators.GSave());
    pageContents.Add(new Operators.GRestore());

    // Add save graphics state operator to properly clear graphics state after new commands
    pageContents.Add(new Operators.GSave());

    #region create xForm

    // Create xForm
    XForm form = XForm.CreateNewForm(document.Pages[1], document);
    document.Pages[1].Resources.Forms.Add(form);
    form.Contents.Add(new Operators.GSave());
    // Define image width and heigh
    form.Contents.Add(new Operators.ConcatenateMatrix(200, 0, 0, 200, 0, 0));
    // Load image into stream
    Stream imageStream = new FileStream(imageFile, FileMode.Open);
    // Add image to Images collection of the XForm Resources
    form.Resources.Images.Add(imageStream);
    XImage ximage = form.Resources.Images[form.Resources.Images.Count];
    // Using Do operator: this operator draws image
    form.Contents.Add(new Operators.Do(ximage.Name));
    form.Contents.Add(new Operators.GRestore());

    #endregion

    pageContents.Add(new Operators.GSave());
    // Place form to the x=100 y=500 coordinates
    pageContents.Add(new Operators.ConcatenateMatrix(1, 0, 0, 1, 100, 500));
    // Draw form with Do operator
    pageContents.Add(new Operators.Do(form.Name));
    pageContents.Add(new Operators.GRestore());

    pageContents.Add(new Operators.GSave());
    // Place form to the x=100 y=300 coordinates
    pageContents.Add(new Operators.ConcatenateMatrix(1, 0, 0, 1, 100, 300));
    // Draw form with Do operator
    pageContents.Add(new Operators.Do(form.Name));
    pageContents.Add(new Operators.GRestore());

    // Restore grahics state with GRestore after the GSave
    pageContents.Add(new Operators.GRestore());
    document.Save(outFile);
}

Remove Graphics Objects using Operator Classes

The operator classes provide great features for PDF manipulation. When a PDF file contains graphics that cannot be removed using the PdfContentEditor class’ DeleteImage method, the operator classes can be used to remove them instead.

The following code snippet shows how to remove graphics. Please note that if the PDF file contains text labels for the graphics, they might persist in the PDF file, using this approach. Therefore search the graphic operators for an alternate method to delete such images.

// For complete examples and data files, please go to https://github.com/aspose-pdf/Aspose.PDF-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_AsposePdf_Operators();

Document document = new Document(dataDir +  "RemoveGraphicsObjects.pdf");
Page page = document.Pages[2];
OperatorCollection oc = page.Contents;

// Used path-painting operators
Operator[] operators = new Operator[] {
        new Operators.Stroke(),
        new Operators.ClosePathStroke(),
        new Operators.Fill()
};

oc.Delete(operators);
document.Save(dataDir +  "No_Graphics_out.pdf");