Tips and tricks #10: Files, long calculation mode

The article describes how to use input and output files in Planetcalc calculators

Tips and tricks series

This article may rely on knowledge you should get from previous articles, so you may want to check them first.

File output

Using file output you can save your calculator output as a binary file. For example the following calculator generates sound tones by user parameters and saves it to wave audio file. The file can be downloaded to the user's PC by clicking on the calculator output parameter link.

PLANETCALC, Sound tone generator

Sound tone generator

Output file format

Sound file

The code excerpt from the calculator above generates the link for downloading output file:

file.SetValue( {filename:form + period 
  + 'Hz_' + bits +'bit' + (sampling/1000) 
  + 'kHz_' +  length + 'ms.wav'
  ,data:[header,data]} );

So to create a downloadable file link you should pass the following structure to the file output:
{ filename, type, data }

  • filename - is a name under which a user browser will save the file after clicking by output file link.
  • type - MIME type of the output file (optional)
  • data - array of ArrayBuffer's, containing the file content.
    N.B. the file data is kept in a user computer memory, so don't generate huge files to avoid out-of-memory issues.

File input

The file input extends the Planetcalc calculator framework capabilities by the option of reading data from local files. You may set the limits on input file types and file size. By default any files of any size are allowed. The calculator will read files larger than 32K in the long calculation mode only. In this mode, your calculator code will be called each time the next data block is read until the end of the file is reached or read stopping by user action or API call.
The following calculator reads input files and draws waveform.

PLANETCALC, Audio file waveform

Audio file waveform

Wave file
  • Drag files here
Digits after the decimal point: 3
File format
The file is very large. Browser slowdown may occur during loading and creation.

The variable representing input file contains an array of file data objects. Each file data object represents a file selected in the file input UI control. It has the following properties:

  • file - file information
  • chunk - data block information
  • data - data buffer

File information

The file property of the file data object contains an object with file properties:

  • name - filename
  • type - file MIME type
  • size - file size in bytes

Data block information

The chunk property of the file data object contains a properties of current read position:

  • index - current block position (starts from 0)
  • total - number of blocks in the file

Data buffer

The data property is the javascript ArrayBuffer containing a chunk of file data. Data property exists in the current file data object only ( the files are read sequentially ).

The example below demonstrates input file API:

// file variable represents input file data here
var currentFile;
for( var i=0;i!=file.length;++i ) {
// only currently processed file data object 
//    has non empty data property
        if ( file[i].data ) { 
            currentFile = file[i]; break;

 var dv = new DataView( );
//start current file reading
if ( currentFile.chunk.index === 0 ) { 

for( var i =0;i!=dv.byteLength;++i) {
     var byte = dv.getUint8(i);
     /// file data processing

//end current file reading
if ( currentFile.chunk.index 
    == ) {
} else {
     //keep context
    progressControl.repeat( contextObject );

Long calculation mode

By switching on 'Long calculation' mode in the calculator properties one may perform a repeating long calculation without UI freeze. In this mode, modern browsers will execute the calculator code in the web worker (separate thread). The calculator code will be repeated, if the long calculation mode API method progressControl.repeat() is called. Otherwise the calculation will be stopped after completion of Calculate function. If the calculator has at least one file input, the calculation is repeated automatically. The calculation can be stopped by the user or by API call progressControl.stop(). The developer can pass some data in the first parameter of the progressControl.repeat( { some : data } ) method. This data can be accessed via progressControl.context; property during the subsequent iteration.

URL copied to clipboard
Creative Commons Attribution/Share-Alike License 3.0 (Unported) PLANETCALC, Tips and tricks #10: Files, long calculation mode