This Mathematica package provides tools to share images and source-code from within Mathematica notebooks directly with Stack Exchange. At its core is a palette, the SE Uploader Palette, that lets you access most of its current features.
On the right, you see how the palette looks under Ubuntu Linux. The buttons give you access to the following features:
- The
Imagebutton lets you upload any selected graphics, cell, selected region as an image. - The
Image (pp)does the same but uses a pixel perfect version. This is only available under Windows and mac OS. - The
Selected Cellbutton works when you have selected one or more cell brackets. It will encode the cell expression as an image and upload it to Stack Exchange. This image can then easily be decoded again, and you get the exact same cells on your local machine. - The
Selected Notebookbutton works equivalently with the difference, that it will encode a whole notebook into an image
All upload buttons copy appropriate markdown-code, URL's or *Mathematica snippets into your clipboard after uploading the data, so that you can directly paste it into your Stack Exchange post.
Navigation
You can upload not only Mathematica graphics and plots. The image upload lets you basically turn almost every selected cell, cell-group or region into an image. Here, I will describe the two most use-cases. First, when you want to share a graphics you have created with e.g. Plot3D, the first step is to select the final graphics by clicking on it
Note the orange frame around the graphic in the image above, which indicates, that the graphic is selected. After that, simply click on Image in the Uploader-palette and a preview dialogue will pop up that looks like this
You buttons for uploading an image either for usage in a Stack Exchange Chat room or for direct usage in an answer or question. Both buttons upload the image to the exact same server and the difference of those two buttons is the following:
- Upload for chat will simply copy the URL of the image into your clipboard. So when you press Ctrl+V after uploading the image, you will get something like
http://i.stack.imgur.com/1jnGB.png. In a Stack Exchange chat-room, you can insert images (that are indeed displayed as images and not as links) by posting a message that consists of a valid image URL. - Upload for site will give you the complete markdown code that is required to insert an image into a Stack Exchange answer/question. What you insert with Ctrl+V will look like this:
and it will be displayed as the following image in a markdown page
For uploading code there are two buttons on the palette. The Selected Cell button lets you upload the currently selected cell. When you have selected several cells, all of them are uploaded. So when you are working in a notebook, simply select the cell-brackets you want to share (note the blue selection at the right)
When you click on Selected Cell you will see a small progress-indicator in the palette that vanishes when the upload is finished. After this, you have a very small Mathematica code snipped in your clipboard that you can share:
Import["http://halirutan.github.io/Mathematica-SE-Tools/decode.m"]["http://i.stack.imgur.com/xc0NO.png"]
Anyone who evaluates the above line will get have your selected code cells inserted into his notebook.
Using the Selected Notebook button works similar. Just click in the notebook you want to share so that it is selected. Then press the Selected Notebook button and wait until the upload is complete.
Memory Limitation: Note that there is a limit of 1MB for uploading cells or notebooks!
This section is probably a bit confusing, so let me explain this in more detail. We always upload images, because this is the only thing that Stack Exchange allows us to do. By the way, we do not really upload the images to a Stack Exchange server, as you might have guessed when looking at the URL. Stack Exchange has some agreement with imgur.com which is a pretty famous image sharer and all the images you insert in a post are hosted there.
The possibility to insert images is pretty nice, but what if you need to share a large expression, that is too large to include it as code-block in an answer? Or you want to share a cell with fancy formatting? Or you want to share a whole Notebook with titles, sections, text, code, etc? You could post a screenshot of this, but then no one can edit your code.
There is a solution: What if we forget for one moment, that an image consists of pixels that represent colours? Then we are dealing with a matrix of numbers. Fortunately, a Mathematica cell or a notebook is from the computers point of view only an array of bytes, which can be represented as numbers too. Wouldn't it be possible to simply turn Mathematica cells or notebooks into a list of numbers and store them as blind passengers in an image? Well, yes this is possible, and it is exactly how we will do it.
When you use the Selected Cell or the Selected Notebook button, the Mathematica expression behind your selection is turned into numbers that are used as pixel of an image.
As seen above, the short Mathematic snippet that decodes an uploaded code-expression has the form
Import["http://halirutan.github.io/Mathematica-SE-Tools/decode.m"]["http://i.stack.imgur.com/xc0NO.png"]
This call consists of two parts.
The first part Import[...] loads the
online version of the SEImageExpressionDecode package.
This package-loading call returns the SEDecodeImageAndPrint function which is then applied to the image at
"http://i.stack.imgur.com/9nBGT.png".
If you have the SETools installed on your local system, the encoding- and decoding-functions are directly accessible.
You cannot only encode cells or notebooks, you can encode any expression you want!
<< SETools`
img = SEEncodeExpression[Expand[(x + y)^10]]
SEDecodeImage[img]
With this, you encode anything you like (without size-limit!) and send this image, for instance in a mail.
Note that uploaded expressions are still images and can be viewed. The above image looks like the one on the right. To make it better visible that those images include encoded expressions, they will always look like the Wolfram Wolf. The image contains the wolf as an alpha-channel which makes the encoded data visible in the background. When you watch closely, you see randomly looking grey-values in the wolf's ears. That's your encoded expression.
Uploading encoded expressions with the SE-Uploader has several limitations. Most importantly, there is a size-limit for uploading expressions of currently 1MB. This size limit has its origin in the behaviour of the Stack Exchange image uploading procedure. Every image that is larger than 1MB is automatically converted into a jpeg image which are lossily compressed images. When the palette encodes the image, it uses PNG which has a lossless compression, so that every single byte will be reconstructed correctly. By converting an image into a jpeg, the encoded Mathematica expression is lost forever. Therefore, we reject encodings that exceed the size-limit.
The palette lets you only encode selected cells and notebooks.
It won't work, if you select a small region inside your code.
Nevertheless, with the palette installed, you can load the SETools package and encode any expression you like as shown above.
Note that the SEEncodeExpression function evaluates its arguments before encoding! Therefore, the following
SEEncodeExpression[1 + 1]
will encode the expression 2 and not the expression 1+1.
You can use Unevaluated[1+1] to prevent the evaluation.
The convenience of easily en- and decoding expressions into images comes at a price: Security.
Seeing the encoded image will not tell you what the expression behind it will do.
Therefore, except for Cell- and Notebook-expressions, the decoding function will return its result in unevaluated form wrapped in HoldComplete.
Encoded images contain a hash to ensure data-consistency.
However, Mathematica's Hash function gives different results for different versions
(try Hash[{1,2,3,4}, "MD5"] in version 10 and 12), and the decode function might give you a warning even
when the data is not corrupted.
This deficiency was fixed in version 131 of the SETools.
You can wrap AbortProtect[..] around the decode call to ignore this warning and decode the expression anyway.
Additionally, make sure you always use the proper decoding function from the SETools package.
For code you share with people who might not have the SETools installed, you can use the URL that
points to this GitHub repository
Import["http://halirutan.github.io/Mathematica-SE-Tools/decode.m"]["http://i.stack.imgur.com/xc0NO.png"]If you have the SETools installed, you can also use
Get["SETools`SEImageExpressionDecode`"]["http://i.stack.imgur.com/xc0NO.png"]
The palette should work on Mathematica versions >= 8.0.4 but it was mainly tested and developed under version 10.0.1. The installation is simple: Copy the SETools package directory into a location where Mathematica can find it. Usually this is the Applications directory in your $UserBaseDirectory. Just evaluate
FileNameJoin[{$UserBaseDirectory, "Applications"}]
to see it. If there is an old installation of the SETools (or the older SEUploader), remove it. Please find detailed steps below.
We have set up an installation script that does all the steps, except deleting old installations, for you. If it finds an old installation, it will prompt you with the location and quit, so that you can remove the old installation. After removing the old files, just start it again and it will proceed through all the steps pointed out in the manual installation section. To start the installation script, simply call
Import["http://goo.gl/rQtfHZ"]
After this, the palette should appear in the Palettes menu and be ready to use.
Old installation packages can be found by simply searching directories in your $Path.
FileNames["SETools", $Path]
FileNames["SEUploader", $Path]
Please remove old installation directories that appear after evaluating the commands above. You can use
DeleteDirectory[dir, DeleteContents -> True]
for that, but note that on Windows this might fail, because there, some files are locked when Mathematica is running. In this case, close Mathematica and do it manually using an explorer.
The easiest way is, to download the whole repository as zip file. Use this master.zip or click the Download ZIP on the right side on this page.
After you have downloaded the file extract it. If you have no tool for this on Windows, you could use the free 7-Zip. Under Mac OSX and Linux this should work out of the box.
Inside the extracted directory, you will find a subdirectory SETools which has the following structure
SETools/
├── FrontEnd
│ └── Palettes
│ └── SEUploader.nb
├── Installer.m
├── Java
│ └── SETools.jar
├── Kernel
│ └── init.m
├── Resources
│ └── banner.png
├── SEImageExpressionDecode.m
├── SEImageExpressionEncode.m
├── SEUploader.m
└── Version.m
Copy the whole SETools directory with all its content to your Applications folder under your $UserBaseDiretory. If everything is in place proceed to the next step.
To make the palette appear, you can simply restart Mathematica. There is another possibility to rebuild the Palette menu which worked fine too in all my tests, but it might not be enough under Windows. Just evaluate
FrontEndExecute[FrontEnd`ResetMenusPacket[{Automatic, Automatic}]]
Basically the installation is nothing more than putting the package directory into a place where Mathematica expects packages and ensuring that there are not more than one installation, because otherwise different java jar libraries might conflict. If the palette does not appear, then either it is not in the right place or you need to restart Mathematica.
If you get java-exceptions when you try to use the palette, then this can have 2 possible reasons. First, if the java-version is not correct, then you will see an error message like the following
JLink`Java::excptn: "A Java exception occurred: java.lang.UnsupportedClassVersionError: de/halirutan/se/tools/SEUploader
In this case, the problem is my fault because I have compiled the used java code with a more recent java version that what is used by Mathematica. Once the SETools are thoroughly tested, this should not happen with supported Mathematica versions and I would be glad, when you report this to me.
Second, you get an exception of the form
java.lang.ClassNotFoundException: de.halirutan.se.tools.SEUploader
Then, the java library SETools.jar is not in the java classpath and can not be found. Please ensure that the file SETools.jar is located in the package directory under
Applications/SETools/Java/SETools.jar
in your $UserBaseDirectory.
If you find bugs or have any other questions, please create a new issue in the bug-tracker. Additionally, you can always ask in the Mathematica chat at Stack Exchange.
Many thanks go to Szabolcs Horvát, who implemented and maintained the first version of the SE-Uploader!