Skip to main content

Layer Management

About 4 min

Layer Management

Layers are used to organize and control the display and editing of entities.

Overview

Layers are an important organizational mechanism in CAD. They allow you to:

  • Group entities by category
  • Control entity visibility
  • Control entity editability (locking)
  • Set default properties such as color and line type

Layer Properties

PropertyTypeDescription
namestringLayer name (unique)
colornumberLayer color (ACI Color Index)
lineTypestringLayer line type
lineWeightnumberLayer line weight
layerOnbooleanLayer On/Off (whether to display)
isLockedbooleanWhether locked
isFrozenbooleanWhether frozen
frozenbooleanWhether frozen (alias for isFrozen)

Layer State Details

Layers have three independent state controls with different effects:

StatePropertiesVisibleSelectableEditableParticipates in regeneration
NormallayerOn=true, isFrozen=false, isLocked=false✓✓✓✓
OfflayerOn=false✗✗✗✓
FrozenisFrozen=true✗✗✗✗
LockedisLocked=true✓✗✗✓

State descriptions:

  • Off (layerOn=false): Layer is not displayed, but entities still participate in regeneration calculations
  • Frozen (isFrozen=true): Layer is not displayed, entities do not participate in regeneration, better performance. Layer 0 and the current layer cannot be frozen
  • Locked (isLocked=true): Layer displays normally, but entities cannot be selected or edited, suitable as a Reference Base Map

Layer Operations

Get Layer

import { Engine } from 'vjcad';

// Get all layers
const layers = Engine.currentDoc.layers;

// Get layer by name
const layer = layers.get('Wall');

// Get current layer
const currentLayer = Engine.currentDoc.CLAYER;
console.log('Current layer:', currentLayer.name);

// Check if layer exists
if (layers.has('Door/Window')) {
  console.log('Door/Window layer exists');
}

Create Layer

import { Engine } from 'vjcad';

const doc = Engine.currentDoc;

// Method 1: Use Engine.createLayer (recommended)
const layer1 = Engine.createLayer("Annotation", {
    color: 1,           // Red
    lineType: "CONTINUOUS",
    layerOn: true,     // Whether to display
    isFrozen: false,   // Whether frozen
    isLocked: false    // Whether locked
});

// Method 2: Use doc.layers.addlayer
if (!doc.layers.itemByName("Construction Line")) {
    doc.layers.addlayer("Construction Line", true, 3);  // Params: name, display, color (green)
}

// Method 3: Use doc.layers.add() (supports overload with options)
if (!doc.layers.has("Annotation")) {
    doc.layers.add("Annotation", {
        color: 3,           // Green
        lineType: "CONTINUOUS",
        layerOn: true,
        frozen: false       // Supports frozen property (alias for isFrozen)
    });
}

// Create auto-named layer
const autoLayer = Engine.createLayer();  // Auto-named as "Layer1", "Layer2", etc.

Set Current Layer

import { Engine } from 'vjcad';

// Method 1: Use Engine shortcut
Engine.setCurrentLayer('Wall');

// Method 2: Direct assignment
Engine.currentDoc.CLAYER = Engine.currentDoc.layers.get('Wall');

Modify Layer Properties

import { Engine } from 'vjcad';

const layer = Engine.getLayerByName('Wall');

// Modify color
layer.color = 5;  // Blue

// Modify line type
layer.lineType = 'DASHED';

// Set visibility (Layer On/Off)
layer.layerOn = false;  // Turn off layer
Engine.regen(true);    // Re-render required

// Lock layer
layer.isLocked = true;  // Cannot select or edit when locked

// Freeze layer
layer.isFrozen = true;  // Invisible and excluded from calculations when frozen
Engine.regen(true);    // Re-render required

Delete Layer

import { Engine } from 'vjcad';

// Delete layer (entities on the layer will be moved to layer 0)
Engine.currentDoc.layers.remove('Temp Layer');

// Note: Layer 0 cannot be deleted

Entities and Layers

Set Entity Layer

import { Engine, LineEnt, Point2D } from 'vjcad';

const line = new LineEnt(new Point2D(0, 0), new Point2D(100, 100));
line.setDefaults();

// Method 1: Set layer ID
line.layerId = Engine.currentDoc.layers.get('Wall').id;

// Method 2: Use Engine method
Engine.setEntityLayer(line, 'Wall');

Engine.addEntities(line);

Select Entities by Layer

import { Engine } from 'vjcad';

// Get all entities on the specified layer
const layer = Engine.currentDoc.layers.get('Wall');
const entities = Engine.currentDoc.currentSpace.entities.filter(
  ent => ent.layerId === layer.id
);

console.log(`Wall layer has ${entities.length} entities`);

ByLayer Color

When entity color is set to 256 (ByLayer), the layer color is used:

import { Engine, LineEnt, Point2D } from 'vjcad';

const line = new LineEnt(new Point2D(0, 0), new Point2D(100, 100));
line.color = 256;  // ByLayer - use layer color
line.setDefaults();

// Set layer
Engine.setEntityLayer(line, 'Wall');

// Actual display color = Wall layer color

Layer State Control

Layer On/Off (layerOn)

Controls whether the layer is displayed. Entities on turned-off layers still participate in regeneration calculations:

import { Engine } from 'vjcad';

const layer = Engine.getLayerByName('Annotation');

// Turn off layer
layer.layerOn = false;
Engine.regen(true);  // Re-render required

// Turn on layer
layer.layerOn = true;
Engine.regen(true);

// Batch control
function showOnlyLayers(layerNames: string[]) {
  const layers = Engine.getLayers();
  layers.forEach(layer => {
    layer.layerOn = layerNames.includes(layer.name);
  });
  Engine.regen(true);
}

showOnlyLayers(['Wall', 'Door/Window']);  // Show only Wall and Door/Window

Lock Control (isLocked)

Entities on locked layers are visible but cannot be selected or edited, suitable as a Reference Base Map:

import { Engine } from 'vjcad';

const layer = Engine.getLayerByName('Reference');

// Lock layer
layer.isLocked = true;
// Entities on the layer are still visible, but:
// - Cannot be selected by click, box select, or Ctrl+A
// - No edit operations can be performed on entities

// Unlock layer
layer.isLocked = false;

Freeze Control (isFrozen)

Frozen layers are not displayed and do not participate in regeneration calculations, with better performance than turning off:

import { Engine } from 'vjcad';

const layer = Engine.getLayerByName('Construction Drawing');

// Freeze layer
layer.isFrozen = true;
Engine.regen(true);  // Re-render required

// Thaw layer
layer.isFrozen = false;
Engine.regen(true);

// Note: Layer 0 and current layer cannot be frozen
// Attempting to freeze current layer will be rejected

Using Layers Quick Query Methods

For scenarios with large numbers of entities (millions), use the Layers collection's quick query methods for better performance:

import { Engine } from 'vjcad';

const layers = Engine.currentDoc.layers;

// Check if layer is visible (layerOn=true and isFrozen=false)
const isVisible = layers.isLayerVisible(layerId);

// Check if layer is selectable (visible and not locked)
const isSelectable = layers.isLayerSelectable(layerId);

// Check if layer is frozen
const isFrozen = layers.isLayerFrozen(layerId);

// Check if layer is locked
const isLocked = layers.isLayerLocked(layerId);

Complete Example

Layer Manager

import { Engine } from 'vjcad';

class LayerManager {
  // Create standard layer set
  static createStandardLayers() {
    const layerDefs = [
      { name: 'Wall', color: 1, lineType: 'CONTINUOUS' },
      { name: 'Door/Window', color: 3, lineType: 'CONTINUOUS' },
      { name: 'Furniture', color: 4, lineType: 'CONTINUOUS' },
      { name: 'Annotation', color: 2, lineType: 'CONTINUOUS' },
      { name: 'Centerline', color: 1, lineType: 'CENTER' },
      { name: 'Reference Base Map', color: 8, lineType: 'CONTINUOUS', isLocked: true },
    ];
    
    for (const def of layerDefs) {
      Engine.createLayer(def.name, {
        color: def.color,
        lineType: def.lineType,
        isLocked: def.isLocked || false
      });
    }
  }
  
  // Show all layers
  static showAll() {
    const layers = Engine.getLayers();
    layers.forEach(layer => {
      layer.layerOn = true;
      layer.isFrozen = false;
    });
    Engine.regen(true);
  }
  
  // Hide other layers (except current layer)
  static hideOthers() {
    const currentLayerName = Engine.getCurrentLayer();
    const layers = Engine.getLayers();
    layers.forEach(layer => {
      layer.layerOn = layer.name === currentLayerName;
    });
    Engine.regen(true);
  }
  
  // Lock all layers (except current layer)
  static lockOthers() {
    const currentLayerName = Engine.getCurrentLayer();
    const layers = Engine.getLayers();
    layers.forEach(layer => {
      layer.isLocked = layer.name !== currentLayerName;
    });
  }
  
  // Unlock all layers
  static unlockAll() {
    const layers = Engine.getLayers();
    layers.forEach(layer => {
      layer.isLocked = false;
    });
  }
  
  // Freeze all layers (except current layer and layer 0)
  static freezeOthers() {
    const currentLayerName = Engine.getCurrentLayer();
    const layers = Engine.getLayers();
    layers.forEach(layer => {
      // Layer 0 and current layer cannot be frozen
      if (layer.name !== '0' && layer.name !== currentLayerName) {
        layer.isFrozen = true;
      }
    });
    Engine.regen(true);
  }
  
  // Thaw all layers
  static thawAll() {
    const layers = Engine.getLayers();
    layers.forEach(layer => {
      layer.isFrozen = false;
    });
    Engine.regen(true);
  }
  
  // Get layer statistics
  static getStatistics(): Map<string, number> {
    const stats = new Map<string, number>();
    const entities = Engine.currentSpace.aliveItems;
    
    for (const ent of entities) {
      const layer = Engine.currentDoc.layers.itemById(ent.layerId);
      const layerName = layer?.name || 'Unknown';
      stats.set(layerName, (stats.get(layerName) || 0) + 1);
    }
    
    return stats;
  }
}

// Usage
LayerManager.createStandardLayers();
Engine.setCurrentLayer('Wall');

// View statistics
const stats = LayerManager.getStatistics();
for (const [name, count] of stats) {
  console.log(`${name}: ${count} entities`);
}

ACI Color Index

Common color index values:

IndexColor
1Red
2Yellow
3Green
4Cyan
5Blue
6Magenta
7White/Black
8Gray
256ByLayer
0ByBlock

Online Examples

The following examples can be run in the Playground:

ExampleDescription
layer/01create.jsCreate Layer
layer/02switch.jsSwitch Current Layer
layer/03visibility.jsLayer Visibility (layerOn)
layer/04getlayers.jsGet Layer List
layer/05getentitiesbylayer.jsGet Entities by Layer
layer/06frozen.jsFreeze Layer (isFrozen)
layer/07locked.jsLock Layer (isLocked)
layer/08states.jsLayer State Comparison

Next Steps