jspaint/README.md

367 lines
22 KiB
Markdown
Raw Normal View History

2014-05-30 07:00:01 +00:00
# [![](images/icons/32x32.png) JS Paint](https://jspaint.app)
2014-09-22 10:13:18 +00:00
2022-01-16 00:29:03 +00:00
A pixel-perfect web-based MS Paint remake and more... [Try it out!](https://jspaint.app)
2015-10-19 19:11:10 +00:00
2022-04-12 00:44:19 +00:00
JS Paint recreates every tool and menu of MS Paint, and even [little-known features](#did-you-know), to a high degree of fidelity.
It supports themes, additional file types, and accessibility features like Eye Gaze Mode and Speech Recognition.
2018-06-13 02:37:33 +00:00
![Screenshot](images/meta/main-screenshot.png)
2015-02-24 00:39:43 +00:00
2022-01-16 00:33:09 +00:00
Ah yes, good old Paint. Not the one with the [ribbons][]
2015-10-19 19:11:10 +00:00
or the [new skeuomorphic one][Fresh Paint] with the interface that can take up nearly half the screen.
2019-11-10 16:38:06 +00:00
(And not the even newer [Paint 3D][].)
2017-06-02 04:59:44 +00:00
[ribbons]: https://www.google.com/search?tbm=isch&q=MS+Paint+Windows+7+ribbons "Google Search: MS Paint Windows 7 ribbons"
[Fresh Paint]: https://www.google.com/search?tbm=isch&q=MS+Fresh+Paint "Google Search: MS Fresh Paint"
[Paint 3D]: https://www.microsoft.com/en-us/store/p/paint-3d-preview/9nblggh5fv99
2015-10-19 19:11:10 +00:00
2022-01-16 00:33:09 +00:00
Windows 95, 98, and XP were the golden years of Paint.
2015-10-19 19:11:10 +00:00
You had a tool box and a color box, a foreground color and a background color,
and that was all you needed.
Things were simple.
But we want to undo more than three actions.
We want to edit transparent images.
2022-01-16 00:33:09 +00:00
We can't just keep using the old Paint.
2015-10-19 19:11:10 +00:00
So that's why I'm making JS Paint.
2022-01-16 00:33:09 +00:00
I want to bring good old Paint into the modern era.
2015-10-19 19:11:10 +00:00
2014-08-10 03:06:33 +00:00
2014-09-29 01:19:48 +00:00
#### Current improvements include:
2022-07-28 19:11:17 +00:00
* Open source ([MIT licensed](LICENSE.txt))
2018-01-22 07:46:27 +00:00
* Cross-platform
* Mobile friendly
* Touch support: use two fingers to pan the view, and pinch to zoom
* Click/tap the selected colors area to swap the foreground and background colors
* **View > Fullscreen** to toggle fullscreen mode, nice for small screens
* Web features
* **File > Load From URL...** to open an image from the Web.
* **File > Upload to Imgur** to upload the current image to Imgur.
* **Paste** supports loading from URLs.
* You can create links that will open an image from the Web in JS Paint. For example, this link will start with an isometric grid as a template: <https://jspaint.app/#load:https://i.imgur.com/zJMrWwb.png>
* Rudimentary **multi-user** collaboration support.
Start up a session at
[jspaint.app/#session:multi-user-test](https://jspaint.app/#session:multi-user-test)
and send the link to your friends!
It isn't seamless; actions by other users interrupt what you're doing, and visa versa.
Sessions are not private, and you may lose your work at any time.
If you want better collaboration support, follow the development of [Mopaint](https://github.com/1j01/mopaint).
* **Extras > Themes** to change the look of the app. Dark mode included.
* [Eye Gaze Mode](https://jspaint.app/#eye-gaze-mode), for use with an eye tracker, head tracker, or other coarse input device, accessible from **Extras > Eye Gaze Mode**. With just a webcam, you can try it out with [Enable Viacam](https://eviacam.crea-si.com/) (head tracker) or [GazePointer](https://sourceforge.net/projects/gazepointer/) (eye tracker).
2020-05-30 09:57:20 +00:00
* [Speech Recognition Mode](https://jspaint.app/#speech-recognition-mode).
Using your voice you can select tools and colors, pan the view ("scroll down and to the left", or "go southwest", etc.), explore the menus (but you can activate any menu item without opening the menus first), interact with windows (including scrolling the history view with "scroll up"/"scroll down" etc.), dictate text with the Text tool, and even tell the application to sketch things (for instance, "draw a house")
2018-01-22 07:46:27 +00:00
* Create an animated GIF from the current document history.
Accessible from the Extras menu or with <kbd>Ctrl+Shift+G</kbd>.
It's pretty nifty, you should try it out!
You might want to limit the size of the image though.
* Load and save [many different palette formats](#color-palette-formats) with **Colors > Get Colors** and **Colors > Save Colors**.
(I made a library for this: <img src="images/anypalette-logo-128x128.png" height="16"> [AnyPalette.js](https://github.com/1j01/anypalette.js).)
* You can also drag and drop palette files into the app to load.
Editing Features:
* Use Alt+Mousewheel to zoom in and out
* Edit transparent images! To create a transparent image,
go to **Image > Attributes...** and select Transparent,
then OK, and then **Image > Clear Image** or use the Eraser tool.
Images with *any* translucent pixels will open in Transparent mode.
* You can crop the image by making a selection while holding <kbd>Ctrl</kbd>
2018-06-29 06:14:31 +00:00
* Keyboard shortcuts for rotation: <kbd>Ctrl+.</kbd> and <kbd>Ctrl+,</kbd> (<kbd><</kbd> and <kbd>></kbd>)
* Rotate by any arbitrary angle in **Image > Flip/Rotate**
* In **Image > Stretch/Skew**, you can stretch more than 500% at once
2019-10-03 19:54:20 +00:00
* Zoom to an arbitrary scale in **View > Zoom > Custom...**
2020-05-30 09:57:20 +00:00
* Zoom to fit the canvas within the window with **View > Zoom > Zoom To Window**
2019-10-03 19:54:20 +00:00
* Non-contiguous fill: Replace a color in the entire image by holding <kbd>Shift</kbd> when using the fill tool
Miscellaneous Improvements:
* [Vertical Color Box mode](https://jspaint.app/#vertical-color-box-mode), accessible from **Extras > Vertical Color Box**
* You can use the Text tool at any zoom level (and it previews the exact pixels that will end up on the canvas).
2019-12-08 00:24:50 +00:00
* Spellcheck is available in the textbox if your browser supports it.
2021-12-07 19:09:12 +00:00
* Resize handles are easier to grab than in Windows 10's Paint.
* Omits some Thumbnail view bugs, like the selection showing in the wrong place.
* Unlimited undos/redos (as opposed to a measly 3 in Windows XP,
or a measly 50 in Windows 7)
* Undo history is *nonlinear*, which means if you undo and do something other than redo, the redos aren't discarded. Instead, a new branch is created in the *history tree*. Jump to any point in history with **Edit > History** or <kbd>Ctrl+Shift+Y</kbd>
* Automatically keeps a backup of your image. Only one backup per image tho, which doesn't give you a lot of safety. Remember to save with **File > Save** or <kbd>Ctrl+S</kbd>! Manage backups with **File > Manage Storage**.
<!--
Half-features:
* When you do **Edit > Paste From...** you can select transparent images.
~~You can even paste a transparent animated GIF and then
hold <kbd>Shift</kbd> while dragging the selection to
smear it across the canvas *while it animates*!~~
Update: This was [due to not-to-spec behavior in Chrome.](https://christianheilmann.com/2014/04/16/browser-inconsistencies-animated-gif-and-drawimage/)
I may reimplement this in the future as I really liked this feature.
* You can open SVG files, though only as a bitmap.
(Note: it may open super large, or tiny. There's no option to choose a size when opening.)
-->
2018-06-13 02:37:33 +00:00
![JS Paint drawing of JS Paint on a phone](images/meta/mobipaint.png)
2014-05-30 07:00:01 +00:00
#### Limitations:
2014-09-22 10:13:18 +00:00
2019-12-16 06:49:57 +00:00
A few things with the tools aren't done yet.
See [TODO.md](TODO.md#Tools)
2014-09-22 10:13:18 +00:00
Full clipboard support in the web app requires a browser supporting the [Async Clipboard API w/ Images](https://developers.google.com/web/updates/2019/07/image-support-for-async-clipboard), namely Chrome 76+ at the time of writing.
In other browsers you can still can copy with <kbd>Ctrl+C</kbd>, cut with <kbd>Ctrl+X</kbd>, and paste with <kbd>Ctrl+V</kbd>,
2014-11-25 05:39:16 +00:00
but data copied from JS Paint can only be pasted into other instances of JS Paint.
External images can be pasted in.
2018-08-24 22:42:37 +00:00
2014-05-30 07:00:01 +00:00
## Supported File Formats
### Image Formats
⚠️ Saving as JPEG will introduce artifacts that cause problems when using the Fill tool or transparent selections.
⚠️ Saving in some formats will reduce the number of colors in the image.
💡 Unlike in MS Paint, you can use **Edit > Undo** to revert color or quality reduction from saving.
This doesn't undo saving the file, but allows you to then save in a different format with higher quality, using **File > Save As**.
💡 Saving as PNG is recommended as it gives small file sizes while retaining full quality.
2021-08-01 17:02:22 +00:00
| File Extension | Name | Read | Write | Read Palette | Write Palette |
|-------------------------------|-------------------------------|:----:|:-----:|:------------:|:-------------:|
| .png | [PNG][] | ✅ | ✅ | 🔜 | |
| .bmp, .dib | [Monochrome Bitmap][BMP] | ✅ | ✅ | 🔜 | ✅ |
| .bmp, .dib | [16 Color Bitmap][BMP] | ✅ | ✅ | 🔜 | ✅ |
| .bmp, .dib | [256 Color Bitmap][BMP] | ✅ | ✅ | 🔜 | ✅ |
2021-08-01 17:02:22 +00:00
| .bmp, .dib | [24-bit Bitmap][BMP] | ✅ | ✅ | N/A | N/A |
| .tif, .tiff, .dng, .cr2, .nef | [TIFF][] (loads first page) | ✅ | ✅ | | |
| .pdf | [PDF][] (loads first page) | ✅ | | | |
| .webp | [WebP][] | 🌐 | 🌐 | | |
| .gif | [GIF][] | 🌐 | 🌐 | | |
| .jpeg, .jpg | [JPEG][] | 🌐 | 🌐 | N/A | N/A |
| .svg | [SVG][] (only default size) | 🌐 | | | |
| .ico | [ICO][] (only default size) | 🌐 | | | |
Capabilities marked with 🌐 are currently left up to the browser to support or not.
If "Write" is marked with 🌐, the format will appear in the file type dropdown but may not work when you try to save.
For opening files, see Wikipedia's [browser image format support table][] for more information.
Capabilities marked with 🔜 are coming soon, and N/A of course means not applicable.
2021-08-01 17:02:22 +00:00
"Read Palette" refers to loading the colors into the Colors box automatically (from an [indexed color][] image),
and "Write Palette" refers to writing an [indexed color][] image.
[PNG]: https://en.wikipedia.org/wiki/Portable_Network_Graphics
[BMP]: https://en.wikipedia.org/wiki/BMP_file_format
2021-08-01 17:02:22 +00:00
[TIFF]: https://en.wikipedia.org/wiki/TIFF
[PDF]: https://en.wikipedia.org/wiki/PDF
[WebP]: https://en.wikipedia.org/wiki/WebP
[GIF]: https://en.wikipedia.org/wiki/GIF
[JPEG]: https://en.wikipedia.org/wiki/JPEG
[SVG]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
[ICO]: https://en.wikipedia.org/wiki/ICO_(file_format)
[indexed color]: https://en.wikipedia.org/wiki/Indexed_color
[browser image format support table]: https://en.wikipedia.org/wiki/Comparison_of_web_browsers#Image_format_support
### Color Palette Formats
With **Colors > Save Colors** and **Colors > Get Colors** you can save and load colors
in many different formats, for compatibility with a wide range of programs.
If you want to add extensive palette support to another application, I've made this functionality available as a library:
<img src="images/anypalette-logo-128x128.png" height="16"> [AnyPalette.js](https://github.com/1j01/anypalette.js)
| File Extension | Name | Programs | Read | Write |
|-------------------|-----------------------------------|-----------------------------------------------------------------------------------|:-------:|:-------:|
| .pal | [RIFF] Palette | [MS Paint] for Windows 95 and Windows NT 4.0 | ✅ | ✅ |
| .gpl | [GIMP][Gimp] Palette | [Gimp], [Inkscape], [Krita], [KolourPaint], [Scribus], [CinePaint], [MyPaint] | ✅ | ✅ |
| .aco | Adobe Color Swatch | Adobe [Photoshop] | ✅ | ✅ |
| .ase | Adobe Swatch Exchange | Adobe [Photoshop], [InDesign], and [Illustrator] | ✅ | ✅ |
| .txt | [Paint.NET] Palette | [Paint.NET] | ✅ | ✅ |
| .act | Adobe Color Table | Adobe [Photoshop] and [Illustrator] | ✅ | ✅ |
| .pal, .psppalette | [Paint Shop Pro] Palette | [Paint Shop Pro] (Jasc Software / Corel) | ✅ | ✅ |
| .hpl | [Homesite] Palette | Allaire [Homesite] / Macromedia [ColdFusion] | ✅ | ✅ |
| .cs | ColorSchemer | ColorSchemer Studio | ✅ | |
2021-06-19 23:58:47 +00:00
| .pal | [StarCraft] Palette | [StarCraft] | ✅ | ✅ |
| .wpe | [StarCraft] Terrain Palette | [StarCraft] | ✅ | ✅ |
| .sketchpalette | [Sketch] Palette | [Sketch] | ✅ | ✅ |
| .spl | [Skencil] Palette | [Skencil] (formerly called Sketch) | ✅ | ✅ |
| .soc | StarOffice Colors | [StarOffice], [OpenOffice], [LibreOffice] | ✅ | ✅ |
| .colors | KolourPaint Color Collection | [KolourPaint] | ✅ | ✅ |
| .colors | Plasma Desktop Color Scheme | [KDE] Plasma Desktop | ✅ | |
| .theme | Windows Theme | [Windows] Desktop | ✅ | |
| .themepack | Windows Theme | [Windows] Desktop | ✅ | |
| .css, .scss, .styl| Cascading StyleSheets | Web browsers / web pages | ✅ | ✅ |
| .html, .svg, .js | any text files with CSS colors | Web browsers / web pages | ✅ | |
[RIFF]: https://en.wikipedia.org/wiki/Resource_Interchange_File_Format
[MS Paint]: https://en.wikipedia.org/wiki/Microsoft_Paint
[Paint.NET]: https://www.getpaint.net/
[Paint Shop Pro]: https://www.paintshoppro.com/en/
[StarCraft]: https://en.wikipedia.org/wiki/StarCraft
[Homesite]: https://en.wikipedia.org/wiki/Macromedia_HomeSite
[ColdFusion]: https://en.wikipedia.org/wiki/Adobe_ColdFusion
[StarOffice]: https://en.wikipedia.org/wiki/StarOffice
[OpenOffice]: https://www.openoffice.org/
[LibreOffice]: https://www.libreoffice.org/
[Sketch]: https://www.sketchapp.com/
[Skencil]: https://skencil.org/
[Photoshop]: https://www.adobe.com/products/photoshop.html
[InDesign]: https://www.adobe.com/products/indesign.html
[Illustrator]: https://www.adobe.com/products/illustrator.html
[Gimp]: https://www.gimp.org/
[Inkscape]: https://inkscape.org/en/
[Krita]: https://www.calligra.org/krita/
[KolourPaint]: http://kolourpaint.org/
[KDE]: https://kde.org/
[Windows]: https://en.wikipedia.org/wiki/Microsoft_Windows
[Scribus]: https://www.scribus.net/
[CinePaint]: http://www.cinepaint.org/
[MyPaint]: http://mypaint.org/
2014-05-30 07:00:01 +00:00
## Did you know?
2014-08-10 03:06:33 +00:00
2018-06-29 06:14:31 +00:00
* There's a black and white mode with *patterns* instead of colors in the palette,
which you can get to from **Image > Attributes...**
2014-10-28 23:09:27 +00:00
* You can drag the color box and tool box around if you grab them by the right place.
2015-02-24 00:39:43 +00:00
You can even drag them out into little windows.
2017-06-02 04:59:44 +00:00
You can dock the windows back to the side by double-clicking on their title bars.
2014-10-28 23:09:27 +00:00
* In addition to the left-click foreground color and the right-click background color,
2018-01-22 07:46:27 +00:00
there's a third color you can access by holding <kbd>Ctrl</kbd> while you draw.
2014-10-28 23:09:27 +00:00
It starts out with no color so you'll need to hold <kbd>Ctrl</kbd> and select a color first.
2018-01-22 07:46:27 +00:00
The fancy thing about this color slot is you can
2019-10-28 18:46:03 +00:00
press and release <kbd>Ctrl</kbd> to switch colors *while drawing*.
2014-10-28 23:09:27 +00:00
2018-01-22 07:46:27 +00:00
* You can apply image transformations like Flip/Rotate, Stretch/Skew or Invert (in the Image menu) either to the whole image or to a selection.
2019-10-28 18:46:03 +00:00
Try scribbling with the Free-Form Select tool and then doing **Image > Invert**
2014-12-08 02:45:23 +00:00
* These Tips and Tricks from [a tutorial for MS Paint](https://www.albinoblacksheep.com/tutorial/mspaint)
2019-10-28 18:46:03 +00:00
also work in JS Paint:
2014-02-07 02:47:16 +00:00
2021-06-19 23:58:47 +00:00
* [x] Brush Scaling (<kbd>+</kbd> & <kbd>-</kbd> on the number pad to adjust brush size)
2014-09-22 10:13:18 +00:00
* [x] "Custom Brushes" (hold <kbd>Shift</kbd> and drag the selection to smear it)
* [x] The 'Stamp' "Tool" (hold <kbd>Shift</kbd> and click the selection to stamp it)
2021-06-19 23:58:47 +00:00
* [x] Image Scaling (<kbd>+</kbd> & <kbd>-</kbd> on the number pad to scale the selection by factors of 2)
2018-01-22 07:46:27 +00:00
* [x] Color Replacement (right mouse button with Eraser to selectively replace the foreground color with the background color)
2019-09-30 15:56:07 +00:00
* [x] The Grid (<kbd>Ctrl+G</kbd> & Zoom to 4x+)
2019-09-29 03:16:51 +00:00
* [x] Quick Undo (Pressing a second mouse button cancels the action you were performing.
I also made it redoable, in case you do it by accident!)
2015-06-15 23:50:31 +00:00
* [ ] Scroll Wheel Bug (Hmm, let's maybe not recreate this?)
2014-10-24 00:54:05 +00:00
2018-08-24 22:42:37 +00:00
## Desktop App
2020-04-19 04:06:20 +00:00
JS Paint can be installed as a PWA, altho it doesn't work offline.
2018-08-24 22:42:37 +00:00
2022-01-16 00:29:03 +00:00
(Also I built it into a desktop app with [Electron][] and [Electron Forge][], but this will use unnecessary system resources and is not recommended. You can follow [this issue](https://github.com/1j01/jspaint/issues/2) for the first release.)
2018-08-24 22:42:37 +00:00
[Electron]: https://electronjs.org/
[Electron Forge]: https://electronforge.io/
2018-06-10 03:50:03 +00:00
## Development Setup
[Clone the repo.](https://help.github.com/articles/cloning-a-repository/)
2018-08-24 22:42:37 +00:00
Install [Node.js][] if you don't have it, then open up a command prompt / terminal in the project directory.
2019-11-10 16:38:06 +00:00
### Testing
Run `npm run lint` to check for code problems.
Run `npm test` to run browser-based tests with Cypress. (It's slow to start up and run tests, unfortunately.)
2018-08-24 22:42:37 +00:00
2019-11-10 16:38:06 +00:00
Run `npm run accept` to accept any visual changes.
This unfortunately re-runs all the tests, rather than accepting results of the previous test, so you could end up with different results than the previous test.
If you use [GitHub Desktop](https://desktop.github.com/), you can view diffs of images, in four different modes.
2018-06-10 03:50:03 +00:00
2019-11-10 16:38:06 +00:00
To open the Cypress UI, first run `npm run test:start-server`, then concurrently `npm run cy:open`
Tests are also run in continuous integration [with Travis CI](https://travis-ci.org/1j01/jspaint).
### Web App (https://jspaint.app)
2018-08-24 22:42:37 +00:00
2021-01-31 04:29:44 +00:00
After you've installed dependencies with `npm i`,
use `npm run dev` to start a live-reloading server.
2018-08-24 22:42:37 +00:00
2021-01-31 04:29:44 +00:00
Make sure any layout-important styles go in `layout.css`.
When updating `layout.css`, a right-to-left version of the stylesheet is generated, using [RTLCSS](https://rtlcss.com/).
2020-12-17 19:58:26 +00:00
You should test the RTL layout by changing the language to Arabic or Hebrew.
Go to **Extras > Language > العربية** or **עברית**.
See [Control Directives](https://rtlcss.com/learn/usage-guide/control-directives/) for how to control the RTL layout.
2018-08-24 22:42:37 +00:00
### Desktop App (Electron)
2022-01-16 00:29:03 +00:00
This is basically ready for release, but as of yet unreleased.
2020-04-19 04:06:20 +00:00
2018-08-24 22:42:37 +00:00
- Install dependencies with `npm i`
2021-01-31 03:59:22 +00:00
- Start the electron app with `npm run electron:start`
2018-08-24 22:42:37 +00:00
2022-01-16 00:29:03 +00:00
[electron-debug][] is included, so you can use <kbd>F5</kbd>/<kbd>Ctrl+R</kbd> to reload and <kbd>F12</kbd>/<kbd>Ctrl+Shift+I</kbd> to open the devtools.
2018-06-10 03:50:03 +00:00
2021-01-31 03:59:22 +00:00
You can build for production with `npm run electron:make`
2018-06-10 03:50:03 +00:00
[Live Server]: https://github.com/1j01/live-server
2018-08-24 22:42:37 +00:00
[Node.js]: https://nodejs.org/
[electron-debug]: https://github.com/sindresorhus/electron-debug
2022-07-28 19:11:17 +00:00
## Deployment
JS Paint can be deployed using a regular web server.
Nothing needs to be compiled.
## Embed in your website
### Simple
Add this to your HTML:
```html
<iframe src="https://jspaint.app" width="100%" height="100%"></iframe>
```
### Advanced
If you want to control JS Paint, loading/saving files, etc.,
there is not a formal API for it yet.
There is a very unstable API, which is not documented.
If you're going to use it, make sure you clone the repository and host your own copy of JS Paint.
(Otherwise it would surely break in the future.)
```html
<iframe src="jspaint/index.html" id="jspaint-iframe" width="100%" height="100%"></iframe>
```
The methods in `systemHooks` can be overridden by a containing page like [98.js.org](https://98.js.org/) which hosts jspaint in a [same-origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) iframe.
This allows integrations like setting the wallpaper as the background of the host page, or saving files to a server.
This API may be removed at any time (and perhaps replaced by something based around `postMessage`).
```js
var jspaint = document.getElementById('jspaint-iframe').contentWindow;
jspaint.systemHooks.showSaveFileDialog = async ({ formats, defaultFileName, defaultPath, defaultFileFormatID, getBlob, savedCallbackUnreliable, dialogTitle }) => { ... };
jspaint.systemHooks.showOpenFileDialog = async ({ formats }) => { ... };
jspaint.systemHooks.writeBlobToHandle = async (save_file_handle, blob) => { ... };
jspaint.systemHooks.readBlobFromHandle = async (file_handle) => { ... };
jspaint.systemHooks.setWallpaperTiled = (canvas) => { ... };
jspaint.systemHooks.setWallpaperCentered = (canvas) => { ... };
```
2022-07-28 19:11:17 +00:00
## License
JS Paint is free and open source software, licensed under the permissive [MIT license](https://opensource.org/licenses/MIT).
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub Repo stars](https://img.shields.io/github/stars/1j01/jspaint?label=GitHub%20Stars&style=social)](https://github.com/1j01/jspaint/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/1j01/jspaint?style=social)](https://github.com/1j01/jspaint/network/members)