TextMaterial

TextMaterialは、テキストレンダリング用のマテリアルを表します。

Properties

backfaceCulling

Type: boolean | undefined

Description: 裏側から見たときにラベルを非表示にするかどうかを指定します。false の場合はラベルの両面を描画し、true の場合は表側のみを描画します。

カメラに追従して立っているラベル（デフォルト）は常に表側が見えるため、影響はありません。影響があるのは次の 2 つの場合です。rotateWithCamera が false のラベルは裏側から見えることがあり、その場合は左右反転して表示されますが、この設定を有効にすると非表示になります。textFacing が "flat" のラベルは地球の外側を表側としているため、この設定を有効にすると、大きなラベルのうち地平線の向こう側に回り込んだ部分も非表示になります。

Default: false

Example:

{
  text: {
    textFacing: "flat",
    backfaceCulling: true
  }
}

backgroundColor

Type: Color | undefined

Description: テキスト背景の色をColorで指定します。

Default: undefined

Example:

import { Color } from "@navaramap/three";

{
  text: {
    backgroundColor: new Color().setHex(0xffffff) // 白背景
  }
}

borderColor

Type: Color | undefined

Description: テキスト背景の境界線の色をColorで指定します。

Default: undefined

Example:

import { Color } from "@navaramap/three";

{
  text: {
    borderColor: new Color().setHex(0x000000) // 黒境界線
  }
}

borderWidth

Type: number | undefined

Description: テキスト境界線の幅を指定します。枠線の高さに対する比率を 0 〜 0.5 の間で指定します。

Default: undefined

Example:

{
  text: {
    borderWidth: 2
  }
}

center

Type: Vec2 | undefined

Description: 中心からのシフト量を指定します。範囲は 0 から 1 の間です。

Default: undefined

Example:

{
  text: {
    center: { x: 0.5, y: 0.0 }
  }
}

clampToGround

Type: boolean | undefined

Description: テキストを地面に固定するかどうかを指定します。

Default: undefined

Example:

{
  text: {
    clampToGround: true
  }
}

color

Type: Color | undefined

Description: テキストの色をColorで指定します。

Default: undefined

Example:

import { Color } from "@navaramap/three";

{
  text: {
    color: new Color().setHex(0x000000)
  }
}

declutter

Type: boolean | undefined

Description: 画面空間でのデクラッター（重なり除去）に参加します。ラベルやスプライトが画面上で重なった場合、優先度の低いものが非表示になります。デフォルトで有効です。すべてのラベルを無条件に描画するには false を設定します。

Default: true

Example:

{
  text: {
    declutter: false
  }
}

declutterPriority

Type: number | undefined

Description: デクラッターの配置優先度です。値が大きいほど重なりの競合に勝ちます。declutter が有効な場合にのみ意味を持ちます。FeatureEvaluator.evaluate() で地物ごとに上書きできます。

Default: 0.0

Example:

{
  text: {
    declutter: true,
    declutterPriority: 1
  }
}

depthTest

Type: boolean | undefined

Description: 前面のモデルが背面のモデルを隠すかどうかを決定する変数です。

Default: true

Example:

{
  text: {
    depthTest: true
  }
}

effectIds

Type: string[] | undefined

Description: 適用する Selective Effect の ID を指定します（例: “bloom”, “outline”）。SelectiveBloomEffectDesc や SelectiveOutlineEffectDesc と連携して使用します。Bloom ではグリフの塗り部分のみが発光し、アウトラインと背景は発光しません。

Default: undefined

Example:

{
  text: {
    effectIds: ["bloom", "outline"]
  }
}

emissiveColor

Type: Color | undefined

Description: 発光色をColorインスタンスで指定します。

Default: undefined

Example:

import { Color } from "@navaramap/three";

{
  text: {
    emissiveColor: new Color().setHex(0xff0000)
  }
}

emissiveIntensity

Type: number | undefined

Description: 発光の強度を指定します。

Default: undefined

Example:

{
  text: {
    emissiveIntensity: 0.5
  }
}

font

Type: string | undefined

Description: 単一のフォントファイルの URL、または view.addFontFamily() で事前に登録したフォントファミリの family 名を指定します。サポートされているファイル形式は ttf、otf、woff、woff2 です。

ファミリ名を指定した場合、text に含まれる文字の Unicode 範囲をカバーするフェイスファイルのみが読み込まれるため、CJK などの大きなスクリプトを複数のフェイスに分割してオンデマンドに読み込めます。

各コードポイントには、faces の並び順で最初に unicodeRanges がそのコードポイントを含むフェイスが使用されるため、範囲が重複する場合は先に定義されたエントリが優先されます。どのフェイスにもカバーされないコードポイントは先頭のフェイス（faces[0]）にフォールバックするため、宣言された unicodeRanges に含まれない文字のためにも先頭のフェイスがダウンロードされる可能性があります。詳細は addFontFamily() を参照してください。

フェイスと Unicode 範囲は手書きする代わりに、スタイルシートの @font-face ルール（例: Google Fonts CSS API）から導出することもできます。詳細は Font Family from CSS を参照してください。

Default: undefined（フォントは読み込まれず、フォントを指定するまでテキストレイヤは描画されません）。

Example (単一フォントファイル):

{
  text: {
    font: "https://example.com/fonts/NotoSansJP-Regular.ttf"
  }
}

Example (登録済みフォントファミリ):

view.addFontFamily({
  family: "MapFont",
  faces: [
    { url: "/fonts/latin.woff2", unicodeRanges: [{ from: 0x0000, to: 0x024f }] },
    { url: "/fonts/cjk.woff2", unicodeRanges: [{ from: 0x4e00, to: 0x9fff }] },
  ],
});

// テキストレイヤのマテリアルで使用:
{
  text: {
    font: "MapFont"
  }
}

geometryTypes

Type: ("point" | "line" | "polygon")[] | undefined

Description: このマテリアルが消費するソースジオメトリのカテゴリーです。"line" を含めるとラインの頂点ごとに、"polygon" を含めるとポリゴンリングの頂点ごとに 1 つのラベルを描画します（リングを閉じる重複頂点はスキップされます）。配列を指定するとデフォルトは置き換えられるため、ポイントジオメトリも描画し続けたい場合は "point" を含めてください。このオプションはジオメトリ構築時に適用されます。レイヤー作成時に指定してください。layer.update() で変更しても読み込み済みのタイルには反映されず、変更後に読み込まれたタイルにのみ適用されます（すべてに反映するにはレイヤーを作り直してください）。

Default: ["point"]

Example:

{
  text: {
    geometryTypes: ["point", "polygon"]
  }
}

height

Type: number | undefined

Description: テキストの高度を指定します。単位はメートルです。

Default: undefined

Example:

{
  text: {
    height: 100 // 100メートル
  }
}

lang

Type: string | undefined

Description: テキストシェーピング用の言語コードを指定します（例: “en”, “ja”, “ar”）。テキストを正しくレンダリングするために使用されます。

Default: undefined

Example:

{
  text: {
    lang: "ja"
  }
}

lineHeight

Type: number | undefined

Description: 複数行テキストの行の高さを、フォント本来の行の高さ（アセンダー − ディセンダー + ラインギャップ）に対する倍率で指定します。

Default: 1.0

Example:

{
  text: {
    lineHeight: 1.2
  }
}

maxWidth

Type: number | undefined

Description: 1 行の最大幅を em 単位（size の倍数）で指定します。この幅を超えると、テキストは単語の境界で折り返されます。0 を指定すると折り返しは無効になります。text 内の明示的な \n 文字は、この設定に関わらず常に改行されます。値が em 単位のため、sizeInMeters の有無に関わらず折り返し幅はテキストサイズに比例します。

Default: 0（折り返しなし）

Example:

{
  text: {
    maxWidth: 10 // 10 em を超える行を折り返す
  }
}

offsetDepth

Type: boolean | undefined

Description: 地球表面との重なりを回避します。テキストが地球表面にめり込まないようにする場合に使用します。

Default: undefined

Example:

{
  text: {
    offsetDepth: true
  }
}

opacity

Type: number | undefined

Description: テキストの不透明度を指定します。範囲は 0.0（完全に透明）から 1.0（完全に不透明）です。

Default: 1.0

Example:

{
  text: {
    opacity: 0.5
  }
}

outlineColor

Type: Color | undefined

Description: テキストアウトラインの色をColorで指定します。

Default: undefined

Example:

import { Color } from "@navaramap/three";

{
  text: {
    outlineColor: new Color().setHex(0x000000) // 黒アウトライン
  }
}

outlineOpacity

Type: number | undefined

Description: テキストアウトラインの不透明度を指定します。範囲は 0.0 から 1.0 です。

Default: undefined

Example:

{
  text: {
    outlineOpacity: 0.8
  }
}

outlineWidth

Type: number | undefined

Description: アウトラインの太さを CSS ピクセル単位で指定します。

Default: 0.0

Example:

{
  text: {
    outlineWidth: 2
  }
}

rotateWithCamera

Type: boolean | undefined

Description: ラベルをカメラに追従して回転させるかどうかを指定します。

true の場合、ラベルは常に視点の方を向きます。textFacing が "upright" のときは画面に正対するビルボードになります。"flat" のときは地表の法線を軸に回転し、テキストが常に左から右に読める向きになります。

false の場合、ラベルはアンカー位置のローカルな東・北・上の座標系に固定され、カメラを動かしても向きは変わりません。"upright" では地表に立って南を向く看板になります。北向きのカメラからは読めますが、真上から見ると縁しか見えずに消え、裏側からは鏡像になります。"flat" では北を上にして地表に描かれ、地図とともに回転します。

FeatureEvaluator から地物ごとに指定することもできます。

Default: true

Example:

{
  text: {
    textFacing: "flat",
    rotateWithCamera: false // 北を上にして地表に描く
  }
}

rotation

Type: number | undefined

Description: ラベルを自身の平面内で、アンカー位置を中心に回転させる角度を度数で指定します。正面から見て時計回りです。回転は textFacing と rotateWithCamera で決まる向きに対して追加で適用されます。ビルボードでは画面上で回転し、地表のラベルでは方位角のように回転します。

回転の中心がテキストのどこになるかは center で決まります。たとえば { x: 0.5, y: 0.5 } ならテキストの中央、{ x: 0.5, y: 0.0 } ならテキストブロックの下端が中心になります。

FeatureEvaluator から地物ごとに指定できるため、レイヤー内のラベルごとに異なる向きにできます。

Default: 0.0

Example:

{
  text: {
    textFacing: "flat",
    rotateWithCamera: false,
    rotation: 45, // 地表上で時計回りに 45 度回転
    center: { x: 0.5, y: 0.5 } // テキストの中央を軸に回転
  }
}

highQuality

Type: boolean | undefined

Description: 高品質なグリフ描画を有効にします。true の場合、テキストは MSDF アトラスを使用し、大きなサイズでも角の鋭さを保ちますが、1 グリフあたりのラスタライズ処理コストは大幅に増加します。false または省略した場合は、デフォルトのシングルチャネル SDF アトラスを使用し、ラスタライズが非常に高速ですが、極端なズーム時に角がわずかに丸くなります。

Default: false

Example:

{
  text: {
    highQuality: true
  }
}

sizeInMeters

Type: boolean | undefined

Description: サイズをメートル単位で指定するかどうか。false の場合、サイズはピクセル単位です。

Default: true

Example:

{
  text: {
    sizeInMeters: true
  }
}

show

Type: boolean | undefined

Description: テキストを表示するかどうかを指定します。

Default: undefined

Example:

{
  text: {
    show: true
  }
}

size

Type: number | undefined

Description: テキストのサイズを指定します。単位はピクセルです。

Default: undefined

Example:

{
  text: {
    size: 16
  }
}

text

Type: string | undefined

Description: 表示するテキスト内容を指定します。

Default: undefined

Example:

{
  text: {
    text: "Tokyo Station"
  }
}

textAlign

Type: string | undefined

Description: 複数行テキストブロック内での行の水平方向の配置を指定します。"left"、"center"、"right" のいずれかを指定します。テキストが複数行になる場合（maxWidth または明示的な \n 文字による）にのみ効果があります。

Default: "center"

Example:

{
  text: {
    textAlign: "left"
  }
}

textFacing

Type: "upright" | "flat" | undefined

Description: ラベルを立てて表示するか、地球表面に寝かせて表示するかを指定します。"upright" はラベルを立てた状態に保ちます。"flat" はラベルをアンカー位置の周辺で地球表面に沿わせて配置します。地球の曲率に沿うため、長いテキストでも両端が地表から浮き上がりません。寝かせたラベルは地表に描かれているように見え、カメラのピッチに応じて短縮されます。

rotateWithCamera との組み合わせで、次の 4 通りの表示になります。

`textFacing`	`rotateWithCamera`	表示
`"upright"`	`true`	画面に正対するビルボード。短縮されません（デフォルト）
`"upright"`	`false`	地表に立つ看板。方位は固定されます
`"flat"`	`true`	地表に描かれ、常に左から右に読める向きに回転します
`"flat"`	`false`	地表に描かれ、北を上にして地図とともに回転します

FeatureEvaluator から facing として地物ごとに指定することもできます。

Default: "upright"

Example:

{
  text: {
    textFacing: "flat"
  }
}

transparent

Type: boolean | undefined

Description: 透明度とアルファブレンディングを有効にします。有効にすると、opacity プロパティを使用して透明度を制御できます。

Default: true

Example:

{
  text: {
    transparent: true,
    opacity: 0.5
  }
}