No, I'm building a tool that does the bare minimum what I require and what I don't find in other open source tools. That doesn't mean of course that contributions related to Photoshop-esque features aren't welcomed.
Yep, though it helps having worked in the photo software industry for five years, having tackled the problems before. Also, BitMappery is reusing zCanvas under the hood for rendering and bitmap blitting. BitMappery is written on top of Vue using Vuex and VueI18n.
The Issue Tracker is your point of contact
Bug reports, feature requests, questions and discussions are welcome on the GitHub Issue Tracker, please do not send e-mails through the development website. However, please search before posting to avoid duplicates, and limit to one issue per post.
Please vote on feature requests by using the Thumbs Up/Down reaction on the first post.
BitMappery works with entities known as Documents. A Document contains several Layers, each of which define their content, transformation, Effects, etc. Each of the nested entity properties has its own factory (see /src/factories/). The Document is managed by the Vuex document-module.js.
The types for each of these are defined in /src/definitions/document.ts.
The Document is rendered one layer at a time onto a Canvas element, using zCanvas. Both the rendering and interaction handling is performed by dedicated "Sprite" classes.
All layer rendering and layer interactions are handled by /src/rendering/canvas-elements/layer_sprite.js. Note that the purpose of the renderer is solely to delegate interactions events to the Layer entity. The renderer should represent the properties of the Layer, the Layer should never reverse-engineer from the onscreen content (especially as different window size and scaling factor will greatly complicate these matters when performed two-way).
All interactions that work across layers (viewport panning, layer selection by clicking on non-transparent pixels and drawing of selections) is handled by a single top level sprite that covers the entire zCanvas area. This sprite is /src/rendering/canvas-elements/interaction-pane.js.
Interactions that start/end from outside the canvas (for instance the opening/closing of a selection or the drawing of a brush stroke outside of the canvas area) are handled by document-canvas.vue where the global DOM coordinates are translated to coordinates relative to the canvas document before being forwarded to the zCanvas event handler. See "Rendering concepts" below for more details on screen-to-document coordinates.
Rendering of transformations, text and effects is an asynchronous operation handled by /src/services/render-service.js. The purpose of this service is to perform and cache repeated operations and eventually maintain the source bitmap represented by the LayerSprite. The LayerSprite invokes the rendering service whenever Layer content changes and manages its own cache.
All types related to the editor are either defined in src/definitions/editor.ts or the more specifically
named files.
BitMappery follows the concepts of the display list as listed in the zCanvas wiki, where BitMappery's document layers are visualized as separate Sprites which can be manipulated as separate interactive on-screen elements. BitMappery additionally adds additional logic related to the viewing of large scale content in smaller fragments.
The zCanvas' DOM element (an HTMLCanvasElement instance) is basically as large as the available area inside the
DOM window allows. The BitMappery document displayed inside may however be larger or smaller than the canvas itself
(depending on the zoom level which is - not yet - standardized in the zCanvas package and custom written for BitMappery using the ZoomableCanvas and ZoomableSprite classes).
What determines the visible area of the zoomed document is the viewport. As such, interactions with the zCanvas element must be translated from global DOM coordinates to a point relative to the BitMappery document, taking into account the current scaling factor and viewport offset. This is handled automatically by all event handlers delegated through zCanvas and the sprites, but needs care when performing rendering operations (such as drawing) and translating these to (non-zoomed and non-panned) source bitmaps.
Mutations can be registered in state history (Vuex history-module.js) in order to provide undo and redo of operations. In order to prevent storing a lot of changes of the same property (for instance when dragging a slider), the storage of a new state is deferred through a queue. This is why history states are enqueued by propertyName:
When enqueuing a new state while there is an existing one enqueued for the same property name, the first state is updated so its redo will match that of the newest state, the undo remaining unchanged. The second state will not be added to the queue.
It is good to understand that the undo/redo for an action should be considered separate from the Vue component that is triggering the transaction, the reason being that the component can be unmounted at the moment the history state is changed (and the component is no longer active).
That's why undo/redo handlers should either work on variables in a local scope, or on the Vuex store when mutating store properties. When relying on store state and getters, be sure to cache their values in the local scope to avoid conflicts (for instance in below example we cache activeLayerIndex as it is used by the undo/redo methods to update a specific Layer. activeLayerIndex can change during the application lifetime before the undo/redo handler fires which would otherwise lead to the wrong Layer being updated.
update( propertyName: string, newValue: any ): void {
// cache the existing values of the property value we are about to mutate...
const existingValue = this.getterForExistingValue;
// ...and the layer index that is used to identify the layer containing the property
const index = this.activeLayerIndex;
const store: Store<BitMapperyState> = this.$store;
// define the method that will mutate the existing value to given newValue
const commit = (): void => store.commit( "updateLayer", { index, opts: { newValue } });
// and perform the mutation directly
commit();
// now define and enqueue undo/redo handlers to reverse and redo the commit mutation
enqueueState( propertyName, {
undo(): void {
store.commit( "updateLayerEffects", { index, opts: { existingValue } });
},
redo(): void {
commit();
},
});
}Whenever an action (that requires an undo state) can be triggered in multiple locations (for instance
inside a component and as a keyboard shortcut in @/src/services/keyboard-service), you can
create a custom handler inside @/src/factories/action-factory to avoid code duplication.
Requires you to register a client id or access token in the developer portal of the third party storage provider. Currently, there is support for Dropbox, Google Drive and S3 storage.
You can enable each of these integrations by providing the required key values for your configuration
by creating a local .env.local-file which will contain your custom configuration. You can create this
file by duplicating the contents of the .env-file provided in the repository.
The project setup is two-fold. You can get all the dependencies through NPM as usual:
npm install
after which you can run:
npm run devto start a local development server with hot module reloadnpm run buildto compile a production packagenpm run testto run the unit testsnpm run lintto run the linter on the source files
The above will suffice when working solely on the JavaScript side of things.
git clone https://github.com/igorski/bitmappery.gitdocker build -t bitmappery .docker run -d -p 5173:5173 --name bitmappery-container bitmapperyOnce the container is started, you can access BitMappery at http://localhost:5173
BitMappery can also use WebAssembly to potentially increase performance of image manipulation.
WebAssembly filtering is a user controllable feature in the preferences pane, as long as the .env file has set
support for VITE_ENABLE_WASM_FILTERS to true.
The source code is C based and compiled to WASM using Emscripten. Because this setup is a little more cumbersome, the repository contains precompiled binaries in the ./src/wasm/bin/-folder meaning you can omit this setup if you don't intend to make changes to these sources.
If you do wish to make contributions on this end, to compile the source (/src/wasm/) C-code to WASM, you will first need to prepare your environment (note the last source call does not permanently update your paths):
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.shnow you can compile all source files to WASM using:
npm run wasm
On a particular (deliberately low powered) configuration, running all filters at their heaviest setting on a particular source takes:
- 7000+ ms in JavaScript
- 558 ms in WebAssembly
- 484 ms in JavaScript inside a Web Worker
- 603 ms in WebAssembly inside a Web Worker
Note that the WebAssembly Web Worker takes a performance hit from converting the ImageData buffer to float32 prior to allocating the buffer in the WASM instance's memory. This could benefit from further tweaking to see if it gets closer to the JavaScript Web Worker performance.
However, as in the current setup the JS solution alone is performant enough and you would need to write the filter code twice, the default for WASM is disabled.
