Simple API

はじめに

QCAD Simple APIは、図面へのエンティティの追加、エンティティの照会や修正(移動、トリム、フィレット、オフセットなど)といった一般的な作業を簡単にする、少数のグローバルなスクリプト関数のセットです。主にスクリプトシェルでの使用や、ファイルから実行する短い手続き型スクリプトでの使用を想定していますが、どのスクリプトからでも使用できます。

Simple APIがカバーしているのは、QCAD API全体のごく一部にすぎません。Simple API自体がECMAScript(JavaScript)で書かれているため、その基盤となるQCAD APIの仕組みを学ぶ出発点としても適しています。ソースコードは、QCADのソースコードのファイル scripts/simple.js および scripts/simple_*.js にあります。

Simple APIの使用

スクリプトシェル(その他 > 開発 > スクリプトシェル)および その他 > 開発 > スクリプトを実行 で起動したスクリプトでは、Simple APIのすべての関数を直接使用できます。たとえば次のように入力します。

addLine(0,0, 100,100);

独自のスクリプトファイル、たとえば対話的スクリプトアクションやコマンドラインツールでは、最初にファイル simple.js をインクルードします。

include("scripts/simple.js");

addLine(0,0, 100,100);

トランザクションを使用して別のドキュメントに振り向けない限り、すべての関数はQCADのアプリケーションウィンドウで現在開いている図面に対して動作します(トランザクションを参照)。

このページのすべての例は、空の図面のスクリプトシェルに貼り付けて実行できます。各例は必要なエンティティを自分で作成します。結果を確認するには、ビュー > オートズーム または関数 autoZoom() を使用します。

規約

座標

位置は3通りの方法で渡すことができます。

• 2つの個別の数値として：addLine(0,0, 100,100)
• 2つの数値の配列として：addLine([0,0], [100,100])
• ベクトルオブジェクトとして：addLine(new RVector(0,0), new RVector(100,100))

角度は常に度単位で指定します。ただし、楕円の開始パラメータと終了パラメータはラジアン単位で指定します。

エンティティの参照

既存のエンティティを扱う関数は、さまざまな形式でエンティティを受け付けます。

• エンティティID(数値)。たとえば 1234。
• 作成関数が返すエンティティオブジェクト。たとえば addLine(...) の戻り値。
• 図面内の位置([x,y] または RVector)：指定した位置に最も近いエンティティが使用されます。
• 形状(たとえば new RLine(0,0, 100,0))：操作は形状にのみ適用され、図面は変更されません。

var l = addLine(0,0, 100,0);
move(l, [0,10]);              // エンティティオブジェクトで指定
move(l.getId(), [0,10]);      // エンティティIDで指定
move([50,20], [0,10]);        // 位置で指定：50,20に最も近いエンティティ

クリック位置

一部の操作では、対応するツールを対話的に使用する際にエンティティのどこをクリックしたかによって結果が変わります。トリムではクリック位置にあるエンティティの部分が残り、フィレットと面取りではクリック位置に最も近いエンティティの端が処理され、オフセットではクリック位置の側に平行線が作成されます。

Simple APIでは、各エンティティ参照の後にクリック位置を続けることができます。エンティティを位置で参照した場合は、その位置がクリック位置を兼ねます。クリック位置を指定しない場合は、エンティティの中点が使用されます。

var line = addLine(0,0, 100,0);
var limit = addLine(70,-20, 70,20);

// lineをlimitまでトリムし、10,0にあるlineの部分を残す：
trim(line, [10,0], limit);

戻り値

• 作成関数は追加されたエンティティを返します。このエンティティは他の関数に渡したり、情報を照会したりできます(たとえば getId()、getLength()、getStartPoint())。
• 変換関数(move、rotate、scale、mirror、lengthen、reverse)は変更されたエンティティを返します。
• その他の修正関数(trim、round、bevel、offset、breakOut、autoTrim、divide、explode、stretch)は、図面に適用されたトランザクションを返します。操作が失敗した場合は undefined を返します。
• エンティティの代わりに形状を渡した場合、変換関数は渡された形状を変更し、その他のすべての関数は結果の形状を配列として返します。

失敗した操作はエラーを発生させません。代わりに、スクリプトシェルに「エンティティはトリムできません。」などの警告が表示されます。

エンティティの作成

addPoint

addPoint(x, y)
addPoint([x, y])

指定した位置に点エンティティを追加します。

for (var i=0; i<10; i++) {
    addPoint(i*10, 0);
}

addLine

addLine(x1, y1, x2, y2)
addLine([x1, y1], [x2, y2])

始点から終点まで線分を追加します。

// 三角形：
addLine(0,0, 100,0);
addLine(100,0, 50,80);
addLine(50,80, 0,0);

addXLine

addXLine(x, y, dx, dy)
addXLine([x, y], [dx, dy])

基点 x,y を通り、方向 dx,dy を持つ無限の線(コンストラクションライン)を追加します。方向は基点からの相対値で指定します。

// 0,0を通る水平および45度のコンストラクションライン：
addXLine(0,0, 1,0);
addXLine([0,0], [1,1]);

addArc

addArc(cx, cy, radius, startAngle, endAngle)
addArc(cx, cy, radius, startAngle, endAngle, reversed)
addArc([cx, cy], radius, startAngle, endAngle, reversed)

指定した中心、半径、開始角度、終了角度で円弧を追加します。角度は度単位です。円弧は開始角度から終了角度まで反時計回りに描かれます。ただし、reversed が true の場合は時計回りになります(省略可能、デフォルトは false)。

// 0度から90度までの4分の1の円弧：
addArc(0,0, 50, 0, 90);

// 0度から90度までの時計回りの円弧(残りの4分の3)：
addArc([0,0], 40, 0, 90, true);

addCircle

addCircle(cx, cy, radius)
addCircle([cx, cy], radius)

指定した中心と半径で円を追加します。

// 同心円：
for (var r=10; r<=50; r+=10) {
    addCircle(0,0, r);
}

addEllipse

addEllipse(cx, cy, mx, my, ratio, startParam, endParam, reversed)
addEllipse([cx, cy], [mx, my], ratio, startParam, endParam, reversed)

楕円または楕円弧を追加します。mx,my は中心からの相対値で表した長軸の端点です。ratio は短軸と長軸の比です。startParam と endParam は、楕円が始まる位置と終わる位置を表すラジアン単位の楕円パラメータです。完全な楕円には 0 と 2*Math.PI を使用します。

// 長半径50、短半径25の完全な楕円：
addEllipse(0,0, 50,0, 0.5, 0, 2*Math.PI, false);

// 回転した楕円の上半分：
addEllipse([0,0], [30,30], 0.3, 0, Math.PI, false);

addPolyline

addPolyline(points, closed, relative)

指定した頂点を通るポリラインを追加します。points は頂点の配列で、各頂点は [x, y]、[x, y, bulge] または [x, y, bulge, relative] として指定します。x, y の代わりに RVector を使用することもできます。

• bulge はこの頂点から始まるセグメントの形状を定義します。0(デフォルト)は直線のセグメント、1 は反時計回りの半円、-1 は時計回りの半円です。その他の値では、その中間の円弧セグメントが作成されます(膨らみは円弧の中心角の4分の1のタンジェントです)。
• relative：この頂点の座標が直前の頂点からの相対座標である場合は true。
• closed：ポリラインを閉じる場合は true(デフォルトは false)。
• relative：すべての頂点の座標を直前の頂点からの相対座標として扱う場合は true(デフォルトは false)。

// 閉じた矩形：
addPolyline([[0,0], [100,0], [100,50], [0,50]], true);

// 2つの半円を持つ長穴形状：
addPolyline([[0,60], [80,60,1], [80,80], [0,80,1]], true);

// 相対座標によるジグザグ線：
addPolyline([[0,100], [10,10], [10,-10], [10,10], [10,-10]], false, true);

addSpline

addSpline(fitPoints, closed)

指定した通過点を通るスプラインを追加します。fitPoints は [x, y] 配列または RVector オブジェクトの配列です。closed が true の場合、スプラインは閉じたスプライン(周期的)になります。

// 開いたスプライン：
addSpline([[0,0], [30,40], [60,0], [90,40]], false);

// 閉じたスプライン：
addSpline([[0,60], [40,80], [80,60], [40,100]], true);

チュートリアルファイルからスクリプトを実行するでは、リサージュ曲線をスプラインとしてプロットする別の例を紹介しています。

addSimpleText

addSimpleText(text, x, y)
addSimpleText(text, x, y, height, angle, font, vAlign, hAlign, bold, italic)
addSimpleText(text, [x, y], height, angle, font, vAlign, hAlign, bold, italic)

指定した位置に1行のテキストを追加します。位置より後の引数はすべて省略可能です。

• height：テキストの高さ(デフォルト 1)
• angle：テキストの角度(度単位、デフォルト 0)
• font：フォント名(デフォルト "Standard")
• vAlign：垂直方向の配置：RS.VAlignTop(デフォルト)、RS.VAlignMiddle、RS.VAlignBase または RS.VAlignBottom
• hAlign：水平方向の配置：RS.HAlignLeft(デフォルト)、RS.HAlignCenter または RS.HAlignRight
• bold、italic：太字または斜体のテキストにする場合は true(TrueTypeフォントのみ)

addSimpleText("Hello World", 0,0);
addSimpleText("Title", [0,20], 10);
addSimpleText("Centered", [50,-20], 5, 0, "Standard", RS.VAlignMiddle, RS.HAlignCenter);
addSimpleText("Rotated", 100,0, 5, 45);

addSolid

addSolid(x1, y1, x2, y2, x3, y3, x4, y4)
addSolid([x1, y1], [x2, y2], [x3, y3], [x4, y4])

3つまたは4つの角を持つソリッド(塗りつぶし領域)を追加します。4つの角を持つソリッドでは、角をジグザグの順序で指定することに注意してください。つまり、1番目の角、2番目の角、次に2番目の角の対角にある角、最後に1番目の角の対角にある角の順です。三角形を作成するには、3番目の角を2回渡します。

// 塗りつぶした正方形：
addSolid(0,0, 50,0, 0,50, 50,50);

// 塗りつぶした三角形：
addSolid([60,0], [110,0], [85,50], [85,50]);

形状、エンティティ、オブジェクトの追加

次の関数は、完全なQCAD APIで作成したオブジェクトを図面に追加します。上記の専用の作成関数では対応できない場合に便利です。

addShape

addShape(shape)
addShape(shape, color, linetype, lineweight)

指定した形状(RLine、RArc、RCircle、REllipse、RPolyline、RSpline、RPoint など)を新しいエンティティとして現在の画層に追加します。オプションで、色(RColor)、線種(名前またはID)、線の太さ(たとえば RLineweight.Weight050)を指定できます。デフォルトでは、現在の色、線種 ByLayer、線の太さ ByLayer が使用されます。

addShape(new RLine(new RVector(0,0), new RVector(100,0)));
addShape(new RCircle(new RVector(50,0), 20), new RColor("red"));
addShape(new RLine(new RVector(0,-20), new RVector(100,-20)), new RColor("blue"), "DASHED", RLineweight.Weight050);

addShapes

addShapes(shapes)

指定した配列内のすべての形状を新しいエンティティとして追加します。

var shapes = [];
for (var i=0; i<5; i++) {
    shapes.push(new RCircle(new RVector(i*20, 0), 8));
}
addShapes(shapes);

addEntity

addEntity(entity)
addEntity(entity, color, linetype, lineweight)

指定したエンティティ(REntity)を図面に追加します。色を指定しない場合は、現在の色が使用されます。

var doc = getDocument();
var data = new RLineData(new RVector(0,0), new RVector(100,50));
var entity = new RLineEntity(doc, data);
addEntity(entity);

addObject

addObject(object)

任意のオブジェクト(エンティティ、画層、ブロックなど)を図面に追加し、追加したオブジェクトを返します。

// 十字を含む "Marker" という名前のブロックを追加：
var doc = getDocument();
var block = addObject(new RBlock(doc, "Marker", new RVector(0,0)));

var l1 = new RLineEntity(doc, new RLineData(new RVector(-5,0), new RVector(5,0)));
l1.setBlockId(block.getId());
addEntity(l1);
var l2 = new RLineEntity(doc, new RLineData(new RVector(0,-5), new RVector(0,5)));
l2.setBlockId(block.getId());
addEntity(l2);

// ブロックを2回挿入：
addEntity(new RBlockReferenceEntity(doc, new RBlockReferenceData(block.getId(), new RVector(0,0), new RVector(1,1), 0.0)));
addEntity(new RBlockReferenceEntity(doc, new RBlockReferenceData(block.getId(), new RVector(50,0), new RVector(2,2), 0.0)));

deleteObject

deleteObject(object)

指定したオブジェクトを図面から削除します。エンティティを削除する場合は、通常は関数 deleteEntity を使う方が便利です。

var line = addLine(0,0, 100,0);
deleteObject(line);

画層と属性

addLayer

addLayer(name)
addLayer(name, color, linetype, lineweight)

指定した名前で新しい画層を追加します。オプションで、色名(デフォルトは "white"。白い背景では黒で表示されます)、線種名(デフォルト "CONTINUOUS")、線の太さ(デフォルト RLineweight.Weight000)を指定できます。新しい画層を返します。指定した名前の画層がすでに存在する場合は undefined を返します。

addLayer("Construction", "gray", "DASHED");
addLayer("Contour", "blue", "CONTINUOUS", RLineweight.Weight050);

hasLayer

hasLayer(name)

指定した名前の画層が図面に存在する場合は true を返します。

if (!hasLayer("Holes")) {
    addLayer("Holes", "red");
}

setCurrentLayer

setCurrentLayer(name)

現在の画層を設定します。以降に追加されるすべてのエンティティは、この画層に配置されます。

addLayer("Holes", "red");
setCurrentLayer("Holes");
addCircle(0,0, 5);
addCircle(50,0, 5);
setCurrentLayer("0");

setCurrentColor

setCurrentColor(color)
setCurrentColor(r, g, b)

以降に追加されるエンティティの色を設定します。色は RColor オブジェクト、または赤、緑、青の値(0～255)として指定できます。色を「画層による」に戻すには new RColor(RColor.ByLayer) を使用します。

setCurrentColor(255, 0, 0);
addCircle(0,0, 10);
setCurrentColor(new RColor("blue"));
addCircle(30,0, 10);
setCurrentColor(new RColor(RColor.ByLayer));
addCircle(60,0, 10);

エンティティの照会

getEntity

getEntity(id)
getEntity(entity)
getEntity(x, y)
getEntity([x, y])

指定したエンティティ参照に対応するエンティティを返します。つまり、指定したIDを持つエンティティ、指定したエンティティの現在の状態、または指定した位置に最も近いエンティティです。エンティティが見つからない場合は undefined を返します。

var circle = addCircle(0,0, 20);
move(circle, [10,0]);

// circleは古い中心を保持したまま、getEntityは現在の状態を返す：
getEntity(circle).getCenter();     // 10,0を返す

// 30,0に最も近いエンティティ：
getEntity(30,0).getRadius();       // 20を返す

getShape

getShape(id)
getShape(entity)
getShape(x, y)
getShape([x, y])

指定したエンティティのジオメトリを形状として返します(線分の場合は RLine、円弧の場合は RArc、ポリラインの場合は RPolyline など)。形状を使うと、図面を変更せずに幾何計算を行うことができます。

addPolyline([[0,0], [100,0], [100,50]], false);

var pl = getShape(50,0);
pl.getLength();                    // 150を返す

getClosestEntity

getClosestEntity(x, y)
getClosestEntity([x, y], range)

指定した位置に最も近いエンティティを返します。range を指定した場合は、その位置からその距離以内にあるエンティティだけが対象になります。エンティティが見つからない場合は undefined を返します。

addLine(0,0, 100,0);
addLine(0,50, 100,50);

getClosestEntity(50,10).getStartPoint();     // 0,0を返す
getClosestEntity([50,25], 5);               // undefinedを返す

getEntityShape

getEntityShape(entity, position)

指定したエンティティオブジェクトの形状を返します。複数の形状で構成される複合エンティティ(ブロック参照、ハッチング、寸法、テキスト)の場合は、指定した位置に最も近い形状が返されます。位置は省略可能です。

// 矩形を含むブロックのブロック参照：
var doc = getDocument();
var block = addObject(new RBlock(doc, "Box", new RVector(0,0)));
var pl = new RPolylineEntity(doc, new RPolylineData());
pl.setShape(new RPolyline([new RVector(0,0), new RVector(40,0), new RVector(40,20), new RVector(0,20)], true));
pl.setBlockId(block.getId());
addEntity(pl);
var ref = addEntity(new RBlockReferenceEntity(doc, new RBlockReferenceData(block.getId(), new RVector(0,0), new RVector(1,1), 0.0)));

// 40,10付近のブロック参照の形状(矩形)：
var s = getEntityShape(getEntity(ref), new RVector(41,10));
s.getLength();                     // 120を返す

getIntersectionPoints

getIntersectionPoints(entity1, entity2)
getIntersectionPoints(entity1, entity2, limited)

指定した2つのエンティティまたは形状の交点を含む配列を返します。エンティティは、エンティティオブジェクト、エンティティID、または形状として指定できます。limited が false の場合、エンティティは無限であるかのように扱われます(線分は延長され、円弧は完全な円として扱われます)。デフォルトは true です。

var line = addLine(-50,0, 50,0);
var circle = addCircle(0,0, 30);
var ips = getIntersectionPoints(line, circle);

// 交点を小さな円でマーク：
for (var i=0; i<ips.length; i++) {
    addCircle(ips[i], 2);
}

isPosition と toVector

isPosition(value)
toVector(value)

isPosition は、指定した値が位置(RVector、または2つか3つの数値の配列)である場合に true を返します。toVector は配列で指定された位置を RVector に変換します。これらの関数は、Simple APIと同じ方法で位置を受け付ける独自の関数を書く際に便利です。

function addCross(pos, size) {
    var p = toVector(pos);
    addLine(p.x-size, p.y, p.x+size, p.y);
    addLine(p.x, p.y-size, p.x, p.y+size);
}

addCross([0,0], 5);
addCross(new RVector(20,0), 5);
isPosition([1,2]);                 // trueを返す
isPosition("abc");                 // falseを返す

エンティティの修正

変換

move

move(entity, dx, dy)
move(entity, [dx, dy])

指定したエンティティを、指定した移動量だけ移動します。

var c = addCircle(0,0, 10);
move(c, 50,0);

rotate

rotate(entity, angle)
rotate(entity, angle, cx, cy)
rotate(entity, angle, [cx, cy])

指定したエンティティを、指定した中心を基準に、指定した角度(度単位)だけ回転します。中心を指定しない場合、エンティティは原点 0,0 を中心に回転します。

// 0,0を中心に回転した放射状の線分：
for (var a=0; a<360; a+=30) {
    var l = addLine(10,0, 50,0);
    rotate(l, a);
}

// 正方形をその中心を基準に回転：
var sq = addPolyline([[100,0], [120,0], [120,20], [100,20]], true);
rotate(sq, 45, [110,10]);

scale

scale(entity, factor)
scale(entity, factor, cx, cy)
scale(entity, factor, [cx, cy])
scale(entity, [sx, sy], [cx, cy])

指定したエンティティを、指定した倍率で拡大縮小します。中心点(位置が変わらない点)のデフォルトは原点 0,0 です。XとYで異なる倍率を配列 [sx, sy] として指定できます。円や円弧など一部のエンティティは、XとYで異なる倍率で拡大縮小できないことに注意してください。

var sq = addPolyline([[0,0], [10,0], [10,10], [0,10]], true);
scale(sq, 3);

var pl = addPolyline([[50,0], [60,0], [60,10], [50,10]], true);
scale(pl, [2,1], [50,0]);

mirror

mirror(entity, x1, y1, x2, y2)
mirror(entity, [x1, y1], [x2, y2])
mirror(entity, new RLine(...))

2点で定義される軸を基準に、指定したエンティティを鏡像反転します。

var pl = addPolyline([[10,0], [40,0], [40,30]], false);
// Y軸を基準に鏡像反転：
mirror(pl, 0,0, 0,100);

元のエンティティを残して鏡像反転したコピーを作成するには、先にエンティティのコピーを追加します。

var arc = addArc(20,0, 10, 0, 180);
var copy = addShape(getShape(arc));
mirror(copy, [0,-10], [0,10]);

トリムと伸長

trim

trim(trimEntity, limitingEntity)
trim(trimEntity, trimPos, limitingEntity, limitingPos)
trim(trimEntity, trimPos, limitingEntity, limitingPos, trimBoth)
trim(trimPos, limitingPos)

エンティティ trimEntity を制限エンティティ limitingEntity までトリムします。トリムされるエンティティのうち、クリック位置 trimPos にある部分が残ります。2つのエンティティが交差しない場合、エンティティは制限エンティティまで延長されます。交点が複数ある場合は、クリック位置 limitingPos に最も近い交点が使用されます。trimBoth が true の場合、両方のエンティティが互いにトリムされます。

var line = addLine(0,0, 100,0);
var limit = addLine(70,-20, 70,20);

// 左側の部分を残す。lineの終点は70,0になる：
trim(line, [10,0], limit);

// 線分を円まで延長：
var line = addLine(0,0, 50,0);
var circle = addCircle(100,0, 20);

// 80,0に最も近い円との交点まで延長：
trim(line, [25,0], circle, [80,0]);      // lineの終点は80,0になる

trimBoth

trimBoth(entity1, entity2)
trimBoth(entity1, pos1, entity2, pos2)
trimBoth(pos1, pos2)

両方のエンティティを、互いの交点までトリムまたは延長します。これは trimBoth を true に設定した trim のショートカットです。

// 接していない2本の線分を延長して100,0にコーナーを作る：
var a = addLine(0,0, 80,0);
var b = addLine(100,20, 100,100);
trimBoth(a, b);

lengthen

lengthen(entity, amount)
lengthen(entity, start, amount)
lengthen(entity, pos, amount)
lengthen(pos, amount)

指定したエンティティを、指定した量だけ伸長します。負の値を指定するとエンティティは縮小されます。デフォルトでは、エンティティは終点側で伸長されます。代わりに始点側で伸長するには start に true を渡すか、伸長する端の近くの位置を渡します。

var line = addLine(0,0, 100,0);
lengthen(line, 20);              // lineの終点は120,0になる
lengthen(line, true, -10);       // lineの始点は10,0になる

var arc = addArc(0,50, 30, 0, 90);
lengthen(arc, [30,50], 10);      // 円弧を始点側で伸長

breakOut

breakOut(entity, pos)
breakOut(entity, pos, removeSegment)
breakOut(pos)

指定したエンティティの、指定した位置にある切片を除去します(切片除去)。切片は、その位置の両側で他のエンティティとの最も近い交点で区切られます。片側に交点がない場合、切片はエンティティの端まで続きます。removeSegment が true(デフォルト)の場合、切片は削除されます。それ以外の場合は、独立したエンティティとして残ります。

var line = addLine(0,0, 100,0);
addLine(30,-10, 30,10);
addLine(70,-10, 70,10);

// 30,0と70,0の間の線分の部分を除去：
breakOut(line, [50,0]);

autoTrim

autoTrim(entity, pos)
autoTrim(pos)

breakOut の逆の動作です。指定したエンティティの、指定した位置にある切片だけを残し、残りを削除します。切片は、その位置の両側で他のエンティティとの最も近い交点で区切られます。

var line = addLine(0,0, 100,0);
addLine(30,-10, 30,10);
addLine(70,-10, 70,10);

// 30,0と70,0の間の部分だけを残す：
autoTrim(line, [50,0]);

divide

divide(entity, pos)
divide(entity, pos1, pos2)
divide(pos)

指定したエンティティを、指定した位置で分割します。開いたエンティティ(線分、円弧、開いたポリラインなど)は、1つの位置では2つに、2つの位置では3つに分割されます。閉じたエンティティ(円、完全な楕円、閉じたポリライン)には2つの位置が必要で、2つに分割されます。

var line = addLine(0,0, 100,0);
divide(line, [40,0]);            // 2本の線分：0..40と40..100

var circle = addCircle(0,50, 20);
divide(circle, [20,50], [-20,50]);   // 2つの半円

コーナー

round

round(entity1, entity2, radius)
round(entity1, pos1, entity2, pos2, radius)
round(entity1, pos1, entity2, pos2, radius, trim)
round(pos1, pos2, radius)

2つのエンティティ間のコーナーを、指定した半径の円弧で丸めます(フィレット)。クリック位置は、エンティティのどちらの端をフィレットするかを示します。trim が true(デフォルト)の場合、両方のエンティティがフィレット円弧までトリムされます。

// コーナーをフィレットした矩形：
var l1 = addLine(0,0, 100,0);
var l2 = addLine(100,0, 100,50);
var l3 = addLine(100,50, 0,50);
var l4 = addLine(0,50, 0,0);

round(l1, l2, 10);
round(l2, l3, 10);
round(l3, l4, 10);
round(l4, l1, 10);

同じポリラインを2回渡し、2つのセグメントのそれぞれにクリック位置を指定することで、ポリラインのコーナーもフィレットできます。

var pl = addPolyline([[0,0], [100,0], [100,50]], false);
round(pl, [50,0], pl, [100,25], 10);

bevel と chamfer

bevel(entity1, entity2, distance)
bevel(entity1, entity2, distance1, distance2)
bevel(entity1, pos1, entity2, pos2, distance1, distance2)
bevel(entity1, pos1, entity2, pos2, distance1, distance2, trim)
bevel(pos1, pos2, distance)

2つのエンティティ間のコーナーを直線で面取りします(チャンファー)。distance1 は1つ目のエンティティに沿ったコーナーから面取り線までの距離、distance2 は2つ目のエンティティに沿った距離です(デフォルトは distance1)。trim が true(デフォルト)の場合、両方のエンティティが面取り線までトリムされます。chamfer は bevel の別名です。

var a = addLine(0,0, 100,0);
var b = addLine(100,0, 100,50);
bevel(a, b, 10);

var c = addLine(0,100, 100,100);
var d = addLine(100,100, 100,150);
chamfer(c, d, 20, 10);

offset

offset(entity, distance)
offset(entity, distance, number)
offset(entity, distance, number, side)
offset(entity, sidePos, distance)
offset(entity, sidePos, distance, number)

線分には平行線を、円弧と円には同心の円弧と円を、楕円やその他のエンティティにはオフセット曲線を作成します。number は作成する平行線の数です(デフォルト 1)。側を指定しない限り、平行線はエンティティの両側に作成されます。側は、エンティティの近くの位置 sidePos、または side(RS.LeftHand、RS.RightHand または RS.BothSides)として指定します。ポリラインとスプラインのオフセットはQCAD Professionalでのみ使用できます。

var line = addLine(0,0, 100,0);
offset(line, 5);                 // 両側に1本ずつ平行線

var line2 = addLine(0,30, 100,30);
offset(line2, 5, 2, RS.LeftHand);    // 左側(上側)に2本の平行線

var circle = addCircle(50,80, 10);
offset(circle, [50,95], 3, 4);   // 外側に4つの同心円

reverse

reverse(entity)
reverse(x, y)

指定したエンティティの方向を反転します。つまり、始点と終点を入れ替えます。

var line = addLine(0,0, 100,0);
line = reverse(line);
line.getStartPoint();            // 100,0を返す

explode

explode(entity)
explode(entity, options)
explode(x, y)

指定したエンティティを、より単純なエンティティに分解します。ポリラインは線分と円弧に、ブロック参照はその内容に、テキストは線分とスプラインに、寸法とハッチングは線分や円弧などに分解されます。元のエンティティは削除されます。

options は省略可能なオブジェクトで、通常はアプリケーション設定から取得される設定を指定します。たとえば { splineSegments: 64, textToPolylines: true } のように指定します。サポートされているオプションは splineTolerance、splineSegments、ellipseSegments、splinesToLineSegments、textToPolylines、textSplineToLineOrArc、multilineTextToSimpleText、circlesToPolylines です。

var pl = addPolyline([[0,0], [100,0,1], [100,50], [0,50]], true);
explode(pl);                     // 3本の線分と1つの円弧

stretch

stretch(x1, y1, x2, y2, dx, dy)
stretch([x1, y1], [x2, y2], [dx, dy])
stretch(area, offset)

2つの角で定義される矩形領域内のすべてのエンティティを、指定した移動量だけストレッチします。領域内に完全に含まれるエンティティは移動され、領域の境界をまたぐエンティティはストレッチされます(領域内にある端点だけが移動されます)。領域は RBox、または閉じた RPolyline 形状として指定することもできます。図面内でエンティティが選択されている場合は、選択されたエンティティだけがストレッチされます。

// 線分で構成された矩形：
addLine(0,0, 100,0);
addLine(100,0, 100,50);
addLine(100,50, 0,50);
addLine(0,50, 0,0);

// 右辺をストレッチして矩形の幅を50単位広げる：
stretch([80,-10], [120,60], [50,0]);

deleteEntity

deleteEntity(entity)
deleteEntity(id)
deleteEntity(x, y)

指定したエンティティを図面から削除します。

var l1 = addLine(0,0, 100,0);
var l2 = addLine(0,10, 100,10);
addLine(0,20, 100,20);

deleteEntity(l1);                // エンティティで指定
deleteEntity(l2.getId());        // エンティティIDで指定
deleteEntity(50,20);             // 位置で指定

paste

paste(sourceDocument, destination, offset, scale, rotation,
      flipHorizontal, flipVertical, toCurrentLayer, overwriteLayers, overwriteBlocks)

ドキュメント sourceDocument の内容を、ドキュメントインターフェース destination に貼り付けます。destination が undefined の場合は、現在の図面に貼り付けます。貼り付けた内容は offset だけ移動され、scale で拡大縮小され、rotation 度だけ回転されます。すべての引数が必須です。

• flipHorizontal、flipVertical：内容を反転する場合は true
• toCurrentLayer：すべてのエンティティを現在の画層に貼り付ける場合は true
• overwriteLayers、overwriteBlocks：同じ名前の既存の画層またはブロックを上書きする場合は true

// オフスクリーンのドキュメントにシンボルを作成：
var symbol = createDocument();
startTransaction(symbol);
addCircle(0,0, 10);
addLine(-10,0, 10,0);
addLine(0,-10, 0,10);
endTransaction();

// 現在の図面に3回貼り付け：
for (var i=0; i<3; i++) {
    paste(symbol, undefined, [i*50, 0], 1+i*0.5, i*15, false, false, false, false, false);
}

トランザクション

startTransaction と endTransaction

startTransaction()
startTransaction(document)
endTransaction()

デフォルトでは、Simple APIの各呼び出しはただちに図面に適用され、個別に元に戻すことができます。startTransaction() と endTransaction() の間では、すべての変更が収集され、endTransaction が呼び出されたときにまとめて適用されます。これには2つの利点があります。

• 多数のエンティティを追加する場合に、はるかに高速です。
• すべての変更を1回の操作で元に戻すことができます。

ドキュメント(RDocument)またはドキュメントインターフェース(RDocumentInterface)を startTransaction に渡すと、すべての変更は現在の図面ではなく、そのドキュメントに適用されます。これは、たとえばファイルにエクスポートするために、バックグラウンドで図面を作成する場合に便利です(createDocumentInterface を参照)。

startTransaction();
for (var x=0; x<=200; x+=10) {
    for (var y=0; y<=200; y+=10) {
        addPoint(x, y);
    }
}
endTransaction();

トランザクションを使用する際は、次の点に注意してください。

• トランザクション内では、変更はまだ図面の一部になっていません。trim や round などの修正関数は、同じトランザクション内で追加されたエンティティを参照できません。
• トランザクション内で作成関数が返すエンティティは、endTransaction の後でも有効なIDを持ちません。そのようなエンティティを後で修正するには、位置で参照してください。
• トランザクション内で追加されたすべてのエンティティは、endTransaction が呼び出された時点の現在の画層に配置されます。トランザクションを開始する前に現在の画層を設定し、画層ごとに別々のトランザクションを使用してください。

startTransaction();
addLine(0,0, 100,0);
addLine(100,0, 100,50);
endTransaction();

// 新しい線分を位置で参照してコーナーをフィレット：
round([50,0], [100,25], 10);

getTransactionDocument と getTransactionDocumentInterface

getTransactionDocument()
getTransactionDocumentInterface()

現在のトランザクションが適用されるドキュメントまたはドキュメントインターフェースを返します。トランザクションの外では、現在のドキュメントとドキュメントインターフェースが返されます。

var doc = createDocument();
startTransaction(doc);
addLine(0,0, 10,0);
getTransactionDocument() === doc;    // trueを返す
endTransaction();

getOperation

getOperation()

現在のトランザクションのオペレーション(RAddObjectsOperation)を返します。トランザクションの外では、明示的に適用する必要がある新しいオペレーションが返されます。これは、たとえばSimple APIの呼び出しと完全なQCAD APIを組み合わせるなど、高度な用途を想定しています。

startTransaction();
addCircle(0,0, 10);
var doc = getTransactionDocument();
var e = new RLineEntity(doc, new RLineData(new RVector(-10,0), new RVector(10,0)));
getOperation().addObject(e);
endTransaction();

ビュー

autoZoom

autoZoom()

図面全体が表示されるように、現在のビューをズームします。

addCircle(1000,1000, 500);
autoZoom();

zoomTo

zoomTo(entity)
zoomTo(entity, margin)
zoomTo([x1, y1], [x2, y2])
zoomTo([x1, y1], [x2, y2], margin)
zoomTo(box, margin)

指定したエンティティ、形状、または矩形領域にズームします。margin は領域の周囲の余白です(ピクセル単位、デフォルト 10)。

addCircle(0,0, 100);
var small = addCircle(80,0, 2);
zoomTo(small, 50);

zoomTo([0,0], [100,100]);

ドキュメントとアプリケーション

getMainWindow

getMainWindow()

QCADのアプリケーションウィンドウ(RMainWindowQt)を返します。

getMainWindow().windowTitle;

getDocumentInterface

getDocumentInterface()

現在の図面のドキュメントインターフェース(RDocumentInterface)を返します。ドキュメントインターフェースは、ドキュメントをそのビューと結び付け、ファイルのインポートとエクスポート、オペレーションの適用、元に戻す、やり直しのための関数を提供します。

addLine(0,0, 100,0);
getDocumentInterface().undo();       // 線分を再び削除する

getDocument

getDocument()

現在のドキュメント(RDocument)を返します。ドキュメントは図面のすべてのエンティティ、画層、ブロックなどを保持し、それらを照会するための関数を提供します。

addLine(0,0, 100,0);
addCircle(0,0, 10);
getDocument().queryAllEntities().length;     // 図面内のエンティティの数

getGraphicsView

getGraphicsView()

現在の図面の、現在アクティブなビュー、または最後にアクティブだったビュー(RGraphicsView)を返します。

addCircle(0,0, 50);
getGraphicsView().autoZoom();

createDocument

createDocument()

ウィンドウに表示されない、新しい空のドキュメントをメモリ内に作成します。このようなオフスクリーンのドキュメントは、トランザクションを使って内容を追加し、その後図面に貼り付けることができます(paste を参照)。

var doc = createDocument();
startTransaction(doc);
addLine(0,0, 100,0);
addLine(100,0, 100,100);
endTransaction();

doc.queryAllEntities().length;       // 2を返す

createDocumentInterface

createDocumentInterface()

新しい空のドキュメントを、ドキュメントインターフェースとともにメモリ内に作成します。ドキュメントインターフェースを使用して、ファイルをインポートまたはエクスポートできます。

var di = createDocumentInterface();
startTransaction(di);
addCircle(0,0, 50);
addSimpleText("Created by script", [-40,-60], 5);
endTransaction();

di.exportFile(QDir.homePath() + "/simple_api_example.dxf", "R27 (2013) DXF");

disableInput、enableInput および isInputEnabled

disableInput()
enableInput()
isInputEnabled()

disableInput は、たとえば時間のかかる処理やアニメーションの実行中にユーザー入力を防ぐため、QCADのアプリケーションウィンドウを無効にします。enableInput はアプリケーションウィンドウを再び有効にし、isInputEnabled は現在ユーザー入力が有効な場合に true を返します。スクリプトの最後には、必ず入力を再び有効にしてください。

update

update()

保留中のイベントを処理し、時間のかかる処理の実行中にユーザーインターフェースが更新されるようにします。update を呼び出す前に、disableInput でユーザー入力を無効にしておく必要があります。

sleep

sleep(milliseconds)

ユーザーインターフェースを最新の状態に保ちながら、指定した時間(ミリ秒単位)だけスクリプトを一時停止します。sleep を呼び出す前に、disableInput でユーザー入力を無効にしておく必要があります。

次の例では、disableInput、sleep、enableInput を使って簡単なアニメーションを表示します。

disableInput();
var c = addCircle(0,0, 10);
autoZoom();
for (var i=0; i<20; i++) {
    c = move(c, 5,0);
    sleep(50);
}
enableInput();

warning

warning(message)

警告メッセージを表示します。スクリプトシェルでは、警告はコマンド履歴に表示されます。それ以外の場合、警告はコンソールに出力されます。

if (getDocument().queryAllEntities().length===0) {
    warning("The drawing is empty.");
}

ユーザー入力

次の関数は、ユーザーに値の入力を求める簡単なダイアログを表示します。ユーザーがダイアログをキャンセルすると、undefined が返されます。

getInt

getInt(title, prompt, value, step, min, max)

ユーザーに整数の入力を求めます。value は初期値(デフォルト 0)、step はスピンボックスの増分(デフォルト 1)、min と max は許容範囲です。

var n = getInt("Circles", "Number of circles:", 5, 1, 1, 100);
if (isNull(n)) {
    warning("Canceled.");
}
else {
    for (var i=1; i<=n; i++) {
        addCircle(0,0, i*10);
    }
}

getDouble

getDouble(title, prompt, value, decimals, min, max)

ユーザーに数値の入力を求めます。value は初期値(デフォルト 0)、decimals は表示する小数点以下の桁数(デフォルト 1)、min と max は許容範囲です。

var r = getDouble("Circle", "Radius:", 25.0, 2, 0.01, 1000);
if (!isNull(r)) {
    addCircle(0,0, r);
}

getText

getText(title, prompt, text)

ユーザーにテキストの入力を求めます。text は初期テキストです(デフォルトは空)。

var t = getText("Label", "Text:", "Hello");
if (!isNull(t)) {
    addSimpleText(t, 0,0, 10);
}

getItem

getItem(title, prompt, items, index, separator)

ドロップダウンリストから項目をユーザーに選択させます。items は、すべての項目を separator(デフォルト ",")で区切った文字列です。index は最初に選択されている項目のインデックスです(デフォルト 0)。選択された項目を返します。ダイアログがキャンセルされた場合は undefined を返します。

var shape = getItem("Shape", "Shape to add:", "Circle,Square,Triangle", 0);
if (shape==="Circle") {
    addCircle(0,0, 50);
}
else if (shape==="Square") {
    addPolyline([[-50,-50], [50,-50], [50,50], [-50,50]], true);
}
else if (shape==="Triangle") {
    addPolyline([[-50,-50], [50,-50], [0,50]], true);
}

例：フランジ

この例では、Simple APIの複数の関数を組み合わせて、ピッチ円、別の画層に配置したボルト穴、角を丸めた四角形の切り抜きを持つフランジを描きます。

addLayer("Center Lines", "gray", "CENTER");
addLayer("Holes", "red");

// 外形：
setCurrentLayer("0");
addCircle(0,0, 100);

// ピッチ円と中心線：
setCurrentLayer("Center Lines");
addCircle(0,0, 75);
addLine(-110,0, 110,0);
addLine(0,-110, 0,110);

// ボルト穴(1つのトランザクションで追加)：
setCurrentLayer("Holes");
startTransaction();
for (var a=0; a<360; a+=45) {
    var angle = a * Math.PI / 180;
    addCircle(75*Math.cos(angle), 75*Math.sin(angle), 8);
}
endTransaction();

// 中央の角を丸めた正方形の切り抜き：
setCurrentLayer("0");
var l1 = addLine(-30,-30, 30,-30);
var l2 = addLine(30,-30, 30,30);
var l3 = addLine(30,30, -30,30);
var l4 = addLine(-30,30, -30,-30);
round(l1, l2, 8);
round(l2, l3, 8);
round(l3, l4, 8);
round(l4, l1, 8);

autoZoom();

切り抜きの線分はトランザクションを使わずに追加されるため、そのまま round に渡すことができます。ボルト穴はトランザクション内で追加されるため、高速に処理され、1回の操作で元に戻すことができます。