Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Soft masks #406

Merged
merged 8 commits into from Oct 27, 2012

Conversation

Projects
None yet
3 participants
Owner

pointlessone commented Sep 30, 2012

Soft masks are used for arbitrary transparency. It's like alpha channel in PNG.

The Prawn::SoftMask module is used to create arbitrary transparency in document. Using a soft mask allows creaing more visually rich documents.

You must group soft mask and graphics it's applied to under save_graphics_state because soft mask is a part of graphic state in PDF.

Example:

pdf.save_graphics_state do                                            
  pdf.soft_mask do                                                    
    pdf.fill_color "444444"                                           
    pdf.fill_polygon [0, 40], [60, 10], [120, 40], [60, 68]           
  end                                                                 
  pdf.fill_color '000000'                                             
  pdf.fill_rectangle [0, 10], 120, 68                                 
end                                                                   
Soft masks
Soft masks are used for arbitrary transparency. It's like alpha channel in PNG.
Member

bradediger commented Oct 1, 2012

Thanks for your contribution @cheba. I'd like to see some good specs around this feature before I merge it, especially because it's an area of the spec that I don't know a lot about.

Thanks,
Brad

pointlessone added some commits Oct 4, 2012

Reuse soft masks
Reuse soft masks whenever it's possible. because of the way soft masks are
created there's some junk may be left. Though this can be solved by adding
optimize_objects opion to the document.
Owner

pointlessone commented Oct 10, 2012

Are there any other concerns to be addressed or this pull request is OK to be merged?

Let's please not monkeypatch pdf-inspector here. I'd welcome a pull request at prawnpdf/pdf-inspector, which we can rev when we do another prawn release.

Owner

pointlessone replied Oct 27, 2012

I'm not sure how to do it. I mean, I will definitely send a pull request to pdf-inspector. But how do I specify dependency on it in prawn? Should I switch dep to github in Gemfile?

Member

bradediger commented Oct 27, 2012

I'd prefer the method name soft_mask over make_soft_mask, as the former is more declarative. What do others think?

Owner

pointlessone commented Oct 27, 2012

make_soft_mask is just a helper for specs. The API is soft_mask.

Member

bradediger commented Oct 27, 2012

Oops, I missed that. Thanks.

On Saturday, October 27, 2012, Alexander Mankuta wrote:

make_soft_mask is just a helper for specs. The API is soft_mask.


Reply to this email directly or view it on GitHubhttps://github.com/prawnpdf/prawn/pull/406#issuecomment-9833101.

Owner

pointlessone commented Oct 27, 2012

I've removed monkey patch for pdf-inspector. Pull request for it in the queue. But now specs are failing. I didn't mess with Gemfile. I assume, new version of pdf-inspector needs to be released to fix this failures. Is this acceptable? Advice what to do if not.

Member

bradediger commented Oct 27, 2012

Locally, you can specify a ref of pdf-inspector to check out:

gem 'pdf-inspector', :git => 'git://github.com/prawnpdf/pdf-inspector', :ref => '123abc'

When merging, we will have to take this into account, and release a new version of pdf-inspector separately as a first step. Then we can bump the gem dependency version in prawn's Gemfile.

Can you make a pull request to prawnpdf/pdf-inspector when you are ready? Thanks!

@bradediger bradediger merged commit aef3d15 into prawnpdf:master Oct 27, 2012

1 check failed

default The Travis build failed
Details
Member

bradediger commented Oct 27, 2012

Manual page looks great! I merged your pdf-inspector pull request and cut a 1.0.2 release, which we are now depending on in Prawn (ef58ce5). Merged.

Contributor

backspace commented Feb 16, 2013

I’m not sure exactly what this feature does, so I was trying to test it out, but when I run the example code given in the documentation, all I get is a blank document. Am I missing something obvious?

Here’s the code I’m executing:

Prawn::Document.generate('soft_mask.pdf') do |pdf| 
  pdf.save_graphics_state do
    pdf.soft_mask do
      pdf.fill_color "444444"
      pdf.fill_polygon [0, 40], [60, 10], [120, 40], [60, 68]
    end
    pdf.fill_color '000000'
    pdf.fill_rectangle [0, 10], 120, 68
  end
end

When I open the blank document in Illustrator, there’s only one path, a rectangle near the bottom of the page. It corresponds to the last fill_rectangle instruction.

I’ve tried using both the master branch and the specific commit by @cheba.

I’m sorry if this is the wrong place to ask. I figured it made sense because this issue already existed, but I could open a new one if that’s better.

Owner

pointlessone commented Feb 16, 2013

@backspace Your code produces seemingly blank document because your mask polygon doesn't intersect your rectangle. Basically, the rectangle is drawn on the area that is outside the mask.

You can try the following code:

Prawn::Document.generate('soft_mask.pdf') do |pdf| 
  pdf.save_graphics_state do
    pdf.soft_mask do
      pdf.fill_color "444444"
      pdf.fill_polygon [0, 40], [60, 10], [120, 40], [60, 68]
    end
    pdf.fill_color '000000'
    pdf.fill_rectangle [0, 50], 120, 68
  end
end

It will produce Ruby:
Screen Shot 2013-02-16 at 11 48 30 PM

Soft masks are a way to manipulate alpha channel in PDF. PDF doesn't treat alpha channel as a part of a color. Instead you have to think in masks. To achieve any kind of transparency in PDF you need to draw in inside soft_mask block. It's converted to greyscale and luminocity of resulting image is treated as an alpha channel for everything you draw after that. Specifically that's why you have to wrap it all in save_graphic_state block. In PDF mask is a part of graphic state. So to be able to isolate effect of soft mask you need separate graphic state.

Contributor

backspace commented Feb 16, 2013

Ah, of course. Thanks. That’s what I was hoping for but got sidetracked. The code I was using is from the method documentation, so I’ve submitted a pull request to replace it with your working example from above.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment