Tutorial: Command Line Tool Scripts

Table of Contents

 

Introduction

Scripts can be used to create command line tools that leverage QCAD functionality. Such a script might for example generate a drawing based on parameters, convert a drawing or analyse a drawing.

Example

The basic structure of a command line tool script can look for example as shown below. This is also a fully functional example script that can be used as command line tool to add a line from 0,0 to 100,100 to a given drawing and export that drawing under a new file name:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
include("scripts/simple.js");
include("scripts/Tools/arguments.js");

function printHelp() {
    print("Usage: " + args[1] + " [OPTION]... <drawing file>");
    print();
    print("This tool does...");
    print();
    print("  -f, -force              Overwrite existing output file");
    print("  -h, -help               Display this help");
    print("  -o, -outfile=FILE       Set output file to FILE");
    print("  -p, -parameter          Some parameter...");
    print("  ...");
    printGenericUsage();
    print();
}

function main() {
    if (testArgument(args, "-h", "-help")) {
        printHelp();
        return;
    }

    if (args.length < 3) {
        print("No input file given. Try -h for help.");
        return;
    }
    
    var inFile = args[args.length - 1];
    if (inFile.indexOf("-") === 0) {
        print("No input file. Try -h for help.");
        return;
    }

    var fi = new QFileInfo(inFile);
    if (!fi.isAbsolute()) {
        inFile = RSettings.getLaunchPath() + QDir.separator + inFile;
        fi = new QFileInfo(inFile);
    }

    var outFile = getArgument(args, "-o", "-outfile");
    if (outFile!==undefined) {
        outFile = getAbsolutePathForArg(outFile);
    }
    else {
        print("No output file. Try -h for help.");
    }

    if (new QFileInfo(outFile).exists() && !testArgument(args, "-f", "-force")) {
        print("Output file exists already, not overwriting: ", outFile);
        print("Use -f to force overwrite");
        return;
    }

    // create new document (off screen):
    var doc = new RDocument(new RMemoryStorage(), new RSpatialIndexNavel());
    var di = new RDocumentInterface(doc);

    // import given file:
    if (di.importFile(inFile) != RDocumentInterface.IoErrorNoError) {
        di.destroy();
        print("Cannot import file:", inFile);
        return;
    }

    // add line to drawing (usine QCAD Simple API):
    startTransaction(di);
    addLine(0,0, 100,100);
    endTransaction()

    // export to given file (-o)
    if (!di.exportFile(outFile)) {
        di.destroy();
        print("Cannot export file:", outFile);
        return;
    }
    
    di.destroy();
}

if (typeof(including)=='undefined' || including===false) {
    main();
}

Running Command Line Tool Scripts

Let's assume this script is saved under scripts/Tools/ExTool/ExTool.js.

It can then be run as follows:

qcad -autostart scripts/Tools/ExTool/ExTool.js -f -o out.dxf in.dxf

If the script is run as part of a web service, be sure to also pass the switches -no-gui and -allow-multiple-instances to tell QCAD that no GUI is available and multiple instances can be run in parallel:

qcad -no-gui -allow-multiple-instances -autostart scripts/Tools/ExTool/ExTool.js -f -o out.dxf in.dxf

On a server you would typically also pass -platform offscreen to run headless (i.e. without an X11 server on Linux):

qcad -platform offscreen -no-gui -allow-multiple-instances -autostart scripts/Tools/ExTool/ExTool.js -f -o out.dxf in.dxf