add support for user-specified notebook plot dimensions

Author: jmcphers

src/cpp/session/modules/NotebookPlots.R

@@ -15,14 +15,15 @@
 
 # creates the notebook graphics device 
 .rs.addFunction("createNotebookGraphicsDevice", function(filename,
-  width, pixelRatio, extraArgs)
+  height, width, units, pixelRatio, extraArgs)
 {
+  # form the arguments to the graphics device creator
   require(grDevices, quietly = TRUE)
   args <- list(
     filename = filename,
     width    = width * pixelRatio,
-    height   = (width * pixelRatio) / 1.618, 
-    units    = "px",
+    height   = height * pixelRatio, 
+    units    = units,
     res      = 96 * pixelRatio)
 
   if (nchar(extraArgs) > 0)
@@ -71,7 +72,8 @@
     # output from the device
     output <- paste(tools::file_path_sans_ext(snapshot), "resized.png",
                     sep = ".")
-    .rs.createNotebookGraphicsDevice(output, width, pixelRatio, extraArgs);
+    .rs.createNotebookGraphicsDevice(output, width / 1.618, width, 
+                                     "px", pixelRatio, extraArgs);
 
     # actually replay the plot onto the device
     tryCatch({

src/cpp/session/modules/rmarkdown/NotebookExec.cpp

@@ -60,11 +60,12 @@ FilePath getNextOutputFile(const std::string& docId, const std::string& chunkId,
 } // anonymous namespace
 
 ChunkExecContext::ChunkExecContext(const std::string& docId, 
-      const std::string& chunkId, int execScope, const std::string& options, 
+      const std::string& chunkId, int execScope, const json::Object& options,
       int pixelWidth, int charWidth):
    docId_(docId), 
    chunkId_(chunkId),
    prevWorkingDir_(""),
+   options_(options),
    pixelWidth_(pixelWidth),
    charWidth_(charWidth),
    prevCharWidth_(0),
@@ -113,12 +114,29 @@ void ChunkExecContext::connect()
    if (execScope_ == kExecScopeChunk)
       initializeOutput();
 
+   // extract knitr figure options if present
+   double figWidth = 0;
+   double figHeight = 0;
+   json::readObject(options_, "fig.width",  &figWidth);
+   json::readObject(options_, "fig.height", &figHeight);
+
    // begin capturing plots 
    connections_.push_back(events().onPlotOutput.connect(
          boost::bind(&ChunkExecContext::onFileOutput, this, _1, _2, 
                      kChunkOutputPlot)));
 
-   error = beginPlotCapture(pixelWidth_, outputPath_);
+   if (figWidth > 0 || figHeight > 0)
+   {
+      // user specified plot size, use it
+      error = beginPlotCapture(figHeight, figWidth, PlotSizeManual, 
+                               outputPath_);
+   }
+   else
+   {
+      // user didn't specify plot size, use the width of the editor surface
+      error = beginPlotCapture(0, pixelWidth_, PlotSizeAutomatic, 
+                               outputPath_);
+   }
    if (error)
       LOG_ERROR(error);
 

src/cpp/session/modules/rmarkdown/NotebookExec.hpp

@@ -42,7 +42,7 @@ class ChunkExecContext
 public:
    // initialize a new execution context
    ChunkExecContext(const std::string& docId, const std::string& chunkId,
-         int execScope, const std::string& options, int pixelWidth, 
+         int execScope, const core::json::Object& options, int pixelWidth, 
          int charWidth);
    ~ChunkExecContext();
 
@@ -74,6 +74,7 @@ class ChunkExecContext
    std::string prevWorkingDir_;
    std::string pendingInput_;
    core::FilePath outputPath_;
+   core::json::Object options_;
 
    int pixelWidth_;
    int charWidth_;

src/cpp/session/modules/rmarkdown/NotebookOutput.cpp

@@ -16,6 +16,7 @@
 #include "SessionRmdNotebook.hpp"
 #include "NotebookCache.hpp"
 #include "NotebookOutput.hpp"
+#include "NotebookPlots.hpp"
 
 #include <boost/foreach.hpp>
 #include <boost/format.hpp>
@@ -152,9 +153,22 @@ Error fillOutputObject(const std::string& docId, const std::string& chunkId,
    else if (outputType == kChunkOutputPlot || outputType == kChunkOutputHtml)
    {
       // plot/HTML outputs should be requested by the client, so pass the path
-      (*pObj)[kChunkOutputValue] = kChunkOutputPath "/" + nbCtxId + "/" + 
-                                   docId + "/" + chunkId + "/" + 
-                                   path.filename();
+      std::string url(kChunkOutputPath "/" + nbCtxId + "/" + 
+                         docId + "/" + chunkId + "/" + 
+                         path.filename());
+
+      // if this is a plot and it doesn't have a display list, hint to client
+      // that plot can't be resized
+      if (outputType == kChunkOutputPlot && path.hasExtensionLowerCase(".png"))
+      {
+         // form the path to where we'd expect the snapshot to be
+         FilePath snapshotPath = path.parent().complete(
+               path.stem() + kDisplayListExt);
+         if (!snapshotPath.exists())
+            url.append("?fixed_size=1");
+      }
+
+      (*pObj)[kChunkOutputValue] = url;
    }
 
    return Success();

src/cpp/session/modules/rmarkdown/NotebookPlots.cpp

@@ -32,6 +32,7 @@
 #include <r/session/RGraphics.hpp>
 
 #define kPlotPrefix "_rs_chunk_plot_"
+#define kGoldenRatio 1.618
 
 using namespace rstudio::core;
 
@@ -45,14 +46,16 @@ namespace {
 class PlotState
 {
 public:
-   PlotState(const FilePath& folder):
+   PlotState(const FilePath& folder, PlotSizeBehavior sizeBehavior):
       plotFolder(folder),
-      hasPlots(false)
+      hasPlots(false),
+      sizeBehavior(sizeBehavior)
    {
    }
 
    FilePath plotFolder;
    bool hasPlots;
+   PlotSizeBehavior sizeBehavior;
    FilePath snapshotFile;
    r::sexp::PreservedSEXP sexpMargins;
    boost::signals::connection onConsolePrompt;
@@ -143,7 +146,9 @@ void removeGraphicsDevice(boost::shared_ptr<PlotState> pPlotState)
 {
    // take a snapshot of the last plot's display list before we turn off the
    // device (if we haven't emitted it yet)
-   if (pPlotState->hasPlots && pPlotState->snapshotFile.empty())
+   if (pPlotState->hasPlots && 
+       pPlotState->sizeBehavior == PlotSizeAutomatic &&
+       pPlotState->snapshotFile.empty())
       saveSnapshot(pPlotState);
 
    // restore the figure margins
@@ -162,7 +167,8 @@ void removeGraphicsDevice(boost::shared_ptr<PlotState> pPlotState)
 
 void onBeforeNewPlot(boost::shared_ptr<PlotState> pPlotState)
 {
-   if (pPlotState->hasPlots)
+   if (pPlotState->hasPlots &&
+       pPlotState->sizeBehavior == PlotSizeAutomatic)
    {
       saveSnapshot(pPlotState);
    }
@@ -188,7 +194,9 @@ void onConsolePrompt(boost::shared_ptr<PlotState> pPlotState,
 } // anonymous namespace
 
 // begins capturing plot output
-core::Error beginPlotCapture(int pixelWidth, const FilePath& plotFolder)
+core::Error beginPlotCapture(double height, double width, 
+                             PlotSizeBehavior sizeBehavior,
+                             const FilePath& plotFolder)
 {
    // clean up any stale plots from the folder
    std::vector<FilePath> folderContents;
@@ -210,11 +218,15 @@ core::Error beginPlotCapture(int pixelWidth, const FilePath& plotFolder)
       }
    }
 
-   // marker for content; this is necessary because on Windows, turning off
-   // the png device writes an empty PNG file even if nothing was plotted, and
-   // we need to avoid treating that file as though it were an actual plot
+   // infer height/width if only one is given
+   if (height == 0 && width > 0)
+      height = width / kGoldenRatio;
+   else if (height > 0 && width == 0)
+      width = height * kGoldenRatio;
+
+   // create state accumulator
    boost::shared_ptr<PlotState> pPlotState = boost::make_shared<PlotState>(
-         plotFolder);
+         plotFolder, sizeBehavior);
 
    // save old figure parameters
    r::exec::RFunction par("par");
@@ -229,26 +241,44 @@ core::Error beginPlotCapture(int pixelWidth, const FilePath& plotFolder)
    pPlotState->sexpMargins.set(sexpMargins);
 
    // create the notebook graphics device
-   error = r::exec::RFunction(".rs.createNotebookGraphicsDevice",
-         plotFolder.absolutePath() + "/" kPlotPrefix "%03d.png",
-         pixelWidth, 
-         r::session::graphics::device::devicePixelRatio(),
-         r::session::graphics::extraBitmapParams()).call();
+   r::exec::RFunction createDevice(".rs.createNotebookGraphicsDevice");
+
+   // the folder in which to place the rendered plots (this is a sibling of the
+   // main chunk output folder)
+   createDevice.addParam(
+         plotFolder.absolutePath() + "/" kPlotPrefix "%03d.png");
+
+   // device dimensions
+   createDevice.addParam(height);
+   createDevice.addParam(width); 
+
+   // sizing behavior drives units -- user specified units are in inches but
+   // we use pixels when scaling automatically
+   createDevice.addParam(sizeBehavior == PlotSizeManual ? "in" : "px");
+
+   // devie parameters
+   createDevice.addParam(r::session::graphics::device::devicePixelRatio());
+   createDevice.addParam(r::session::graphics::extraBitmapParams());
+   error = createDevice.call();
    if (error)
    {
       // this is fatal; without a graphics device we can't capture plots
       return error;
    }
 
-   // turn on display list recording so we can do intelligent resizing later
-   r::exec::RFunction devControl("dev.control");
-   devControl.addParam("displaylist", "enable");
-   error = devControl.call();
-   if (error)
+   // if sizing automatically, turn on display list recording so we can do
+   // intelligent resizing later
+   if (sizeBehavior == PlotSizeAutomatic)
    {
-      // non-fatal since we'll do best-effort resizing in the absence of
-      // display lists
-      LOG_ERROR(error);
+      r::exec::RFunction devControl("dev.control");
+      devControl.addParam("displaylist", "enable");
+      error = devControl.call();
+      if (error)
+      {
+         // non-fatal since we'll do best-effort resizing in the absence of
+         // display lists
+         LOG_ERROR(error);
+      }
    }
 
    // set notebook-friendly figure margins 

src/cpp/session/modules/rmarkdown/NotebookPlots.hpp

@@ -34,7 +34,15 @@ namespace modules {
 namespace rmarkdown {
 namespace notebook {
 
-core::Error beginPlotCapture(int pixelWidth, const core::FilePath& plotFolder);
+enum PlotSizeBehavior
+{
+   PlotSizeAutomatic,
+   PlotSizeManual
+};
+
+core::Error beginPlotCapture(double height, double width, 
+      PlotSizeBehavior sizeBehavior, 
+      const core::FilePath& plotFolder);
 
 core::Error initPlots();
 

src/cpp/session/modules/rmarkdown/SessionRmdNotebook.cpp

@@ -209,8 +209,10 @@ Error setChunkConsole(const json::JsonRpcRequest& request,
       s_execContext->disconnect();
 
    // create the execution context and connect it immediately if necessary
-   s_execContext.reset(new ChunkExecContext(docId, chunkId, execScope, options, 
-            pixelWidth, charWidth));
+   const json::Object& optionsJson = jsonOptions.type() == json::ObjectType ? 
+      jsonOptions.get_obj() : json::Object();
+   s_execContext.reset(new ChunkExecContext(docId, chunkId, execScope, 
+            optionsJson, pixelWidth, charWidth));
    if (s_activeConsole == chunkId)
       s_execContext->connect();
 

src/gwt/src/org/rstudio/studio/client/workbench/views/source/editors/text/ChunkOutputWidget.java

@@ -17,6 +17,7 @@
 import org.rstudio.core.client.ColorUtil;
 import org.rstudio.core.client.VirtualConsole;
 import org.rstudio.core.client.dom.DomUtils;
+import org.rstudio.core.client.dom.ImageElementEx;
 import org.rstudio.core.client.js.JsArrayEx;
 import org.rstudio.core.client.widget.FixedRatioWidget;
 import org.rstudio.core.client.widget.PreWidget;
@@ -659,12 +660,24 @@ private void showPlotOutput(String url, final boolean ensureVisible)
 
       final Image plot = new Image();
 
-      final FixedRatioWidget fixedFrame = new FixedRatioWidget(plot, 
-                  ChunkOutputUi.OUTPUT_ASPECT, 
-                  ChunkOutputUi.MAX_PLOT_WIDTH);
-
-      root_.add(fixedFrame);
+      if (isFixedSizePlotUrl(url))
+      {
+         // if the plot is of fixed size, emit it directly, but make it
+         // initially invisible until we get sizing information (as we may 
+         // have to downsample)
+         plot.setVisible(false);
+         root_.add(plot);
+      }
+      else
+      {
+         // if we can scale the plot, scale it
+         FixedRatioWidget fixedFrame = new FixedRatioWidget(plot, 
+                     ChunkOutputUi.OUTPUT_ASPECT, 
+                     ChunkOutputUi.MAX_PLOT_WIDTH);
 
+         root_.add(fixedFrame);
+      }
+  
       DOM.sinkEvents(plot.getElement(), Event.ONLOAD);
       DOM.setEventListener(plot.getElement(), createPlotListener(plot, 
             ensureVisible));
@@ -977,13 +990,32 @@ public void onBrowserEvent(Event event)
          {
             if (DOM.eventGetType(event) != Event.ONLOAD)
                return;
+            
+            // if the image is of fixed size, just clamp its width while
+            // preserving its aspect ratio
+            if (isFixedSizePlotUrl(plot.getUrl()))
+            {
+               ImageElementEx img = plot.getElement().cast();
+               img.getStyle().setProperty("height", "auto");
+               img.getStyle().setProperty("width", "100%");
+               img.getStyle().setProperty("maxWidth", 
+                     Math.min(ChunkOutputUi.MAX_PLOT_WIDTH, 
+                              img.naturalWidth()) + "px");
+            }
 
+            plot.setVisible(true);
+            
             renderTimeout.cancel();
             completeUnitRender(ensureVisible);
          }
       };
    }
 
+   private boolean isFixedSizePlotUrl(String url)
+   {
+      return url.contains("fixed_size=1");
+   }
+   
    @UiField Image clear_;
    @UiField Image expand_;
    @UiField HTMLPanel root_;