DjVu.js Documentation

Если Вам очень требуется документация на русском языке, создайте "issue" в этом проекте, и я, скорее всего, переведу на русский основные части данной документации. Я не сделал этого до сих пор, потому что я очень сомневаюсь, что кому-то это в принципе нужно.

General information

Currently, the following parts of the DjVu format are implemented and supported.

Codecs:

• IW44 codec (Wavelet transform of an image). Both decoding and encoding parts are implemented. Although there is one issue - it's not clear how to scale different layers when they are encoded in different resolutions (and correspondingly have different sizes). Now it's scaled just through duplicating pixels (when we scale an image up). The result is good (in my opinion) but tests say that it's an erroneous way of scaling, since the library creates the image which is different from the image created by the WinDjView program (it's hard to differ both images with the naked eye, but it's so when you make a pixel-to-pixel comparison).

• ZP codec (eventual coding of bit stream). The codec is fully implemented.

• BZZ codec (coding of arbitrary byte strings). It is implemented in terms of encoding as well as in terms of decoding, but there may be some issues concerned with encoding of large volume of data (it must be split into parts, but as far as I remember now it's encoded at once).

• JB2 codec (coding of black-white images and symbols). It is implemented only in terms of decoding, and even not fully. There are 2-3 record types that are kinda supported, but I didn't test the code whether it works at all, since I don't have suitable djvu documents, which contains such records.

Chunks that aren't supported at all::

• ANTa and ANTz - annotations.
• FORM:THUM and TH44 - thumbnails.
• BGjp and FGjp - jpeg encoded images
• Smmr - G4 encoded mask.

All other chunks are supported, more or less, considering the limitations that arise due to the incomplete implementation of the codecs. In case of TXTz and TXTa only text information is decoded and parsed.

How to run/build/debug it

There are 2 parts of the project - the library and the viewer. Correspondingly, you can see the 2 directories - library and viewer. Up to a certain point, both directories can be considered as separate projects, but of course the viewer depends on the library, but the only thing that connected the directories is the fact, that the eventual build file (library/dist/djvu.js) is also copied to the directory of the viewer, just in order to make it possible to run viewer when it's debugged and developed.

In order to run the viewer locally and to build the library you have to install Node.js. Now I use Node.js v8.7.0 and npm 5.4.2, if you have an older version of node/npm I can't guarantee, that the following scripts will work correctly.

How to build it all

The most simple way to get the final build files, is to execute

npm run make

right in the root folder of the project. The command will do the following steps (which may be run manually as well):

1. npm run clean - an alias for git clean -fdX - just removes all untracked files, but keep new manually created files.
2. npm run install - executes npm install in the library and in the viewer folders, installing all required dependencies.
3. npm run build - executes npm run build in the library and in the viewer folders, creating the final builds of the library and of the viewer, and then runs npm run copy - the command which just copies all 3 build files into the /build directory in the root folder of the project.

If after execution of npm run make in the root folder of the project you see the /build folder containing djvu.js, djvu_viewer.js and djvu_viewer.css, it means that all was run successful and you have the final builds of the library and the viewer.

All further information is more detailed. Read it, if you want to start the debug server locally and contribute to the project, or if the npm run make works incorrectly.

How to start the debug server and run DjVu.js Viewer

Open the console, head to the library folder, and execute

npm install

in order to install required dependencies and then

npm run build

in order to build the library into one file. The final result will be in the library/dist/ folder, the name if the file is djvu.js. Also the file will be copied to viewer/public/tmp. It's required for the viewer only.

Then, head to the viewer folder, and run

npm install

And then

npm run start

In order to start the viewer. If everything is ok, then you should see the new tab is opened in your browser with the viewer inside. The viewer is build on the React.js, and the project is created via create-react-app module, so when you change any file of the viewer, it will be recompiled and the tab will be reloaded automatically.

Other commands which may be useful

In the library folder, you can run

• npm run watch - watches the files of the library and recompiled the library on every change. If you started the viewer and want to make some changes in the source files of the library, this command is that you need (should be run in a separate console instance).

• npm run start - just starts a simple static server. When it's done, you may head to the http://localhost:9000/ to see the old app. However the app is poorly maintained now, since I decided to focus on the viewer. I use the app mostly to see the meta data of djvu files, but it also can convert pictures into djvu and split a djvu file (extracting a range of pages). The app is in Russian, but if you are really interested in it, I can translate it into English, however there is not too much text, so you can guess by yourself, what buttons to click :) The app works with the bundle as well as the tests page (http://localhost:9000/tests.html). But npm run start also starts npm run watch, so the bundle should be created automatically, even if you didn't start the build process manually. Other .html files are to debug the library, usually I use sync.html for that.

• npm run build - builds the library, the result file is library/dist/djvu.js.

In case of the viewer, there are the following commands:

• npm run start - start a debug server and rebuild the viewer on each change and reload the page after that.

• npm run build - create a production build, the files that required are .js and .css files inside viewer/build/static/js and viewer/build/static/css folders, their names are random.

All other commands you can see in the corresponding package.json file, they are trivial and rarely used separately.

If something went wrong

If there are some errors, and you can't build/start the viewer or the library, the following clauses may be useful.

• Note what version of Node.js/npm you have installed and take into account what version I use.
• If the npm install fails, remove the corresponding node_modules folder and try to run it again. I myself have this issue sometimes, but this simple action fix it, and usually then npm install works correctly. (Or try to run npm install several times)
• If you still have problems, feel free to create an issue in this project. The library isn't well known and only being developed, so I don't pay much attention to the documentation and focus mostly on the developing, but if it's required I will improve the documentation and answer all your questions as soon as possible.