OpeningDesign/ifc-language-server

Fork 0

Ryan Schultz 788b42cb6a updated readme.md

2025-12-07 20:53:56 -06:00

11 KiB

Raw Permalink Blame History

IFC Language Server for VSCode/VSCodium

A Visual Studio Code extension providing comprehensive language support for Industry Foundation Classes (IFC) files.

Features

🔍 Go to Definition (F12)

Jump directly to the definition of any IFC entity reference.

Click on an entity reference like #123 and press F12
Navigate instantly to where that entity is defined
Works across the entire IFC file

🔎 Find All References (Shift+F12)

Find all locations where an IFC entity is used.

Right-click on an entity definition or reference
Select "Find All References" or press Shift+F12
See all references in the References panel
Click any reference to jump to that location

💡 Hover Information

View detailed information about IFC entities on hover.

Hover over any entity reference (e.g., #123)
See the complete entity definition
View hierarchical dependency tree showing all referenced entities
Understand relationships at a glance

📖 Documentation Links (Ctrl+Click)

Quick access to official buildingSMART documentation.

Ctrl+Click (or Cmd+Click on Mac) on any IFC entity type name
Automatically opens the correct documentation page in your browser
Supports all schema versions:
- IFC2X3: 653 entities with package-based URLs
- IFC4: Standard entity URLs
- IFC4X3: 876 entities with proper PascalCase URLs
Schema version automatically detected from FILE_SCHEMA line

🌲 IFC Entity Hierarchy View

Visual tree view of entity structure.

Open the "IFC Entity Hierarchy" view in the Explorer sidebar
See hierarchical relationships between entities
Expand/collapse entity branches
Click any entity to jump to its definition
Refresh to update after file changes

🔗 IFC Entity References View

Browse all entity references in your IFC file.

Open the "IFC Entity References" view in the Explorer sidebar
See a list of all entities and their references
Shows reference count for each entity
Click to navigate to definitions or references
Refresh to update after file changes

📝 Document Symbols (Ctrl+Shift+O)

Quick navigation through IFC entities.

Press Ctrl+Shift+O (or Cmd+Shift+O on Mac)
See an outline of all IFC entities in the file
Type to filter entities
Click to jump to any entity definition
Also visible in the "Outline" view

🎨 Syntax Highlighting

Enhanced syntax coloring for IFC files.

Entity references (#123) highlighted distinctly
Entity types (IFCPROJECT, IFCWALL) color-coded
String values and numbers styled appropriately
Comments clearly distinguished
Improved readability for large IFC files

Right-click context menu for common operations.

Show in Hierarchy: Reveal entity in the hierarchy tree view
Show References: Display all references in the references view
Go to Definition: Jump to entity definition
Find All References: Find all usages
Quick access to frequently used features

Installation

From VSIX File

Download the .vsix file from the releases page
Open VSCode/VSCodium
Go to Extensions view (Ctrl+Shift+X)
Click the "..." menu at the top of the Extensions view
Select "Install from VSIX..."
Browse to and select the downloaded .vsix file
Click "Install"
Reload VSCode/VSCodium when prompted

From Source

Clone the repository

git clone https://github.com/yourusername/ifc-language-server.git
cd ifc-language-server

Install dependencies
```
npm install
```
Compile the extension
```
npm run compile
```
Run in development mode
- Press F5 in VSCode/VSCodium
- A new "Extension Development Host" window will open
- Open any .ifc file to test the extension
Package as VSIX (optional)
```
npm install -g vsce
vsce package
```
This creates a .vsix file you can install or distribute.

Usage

Opening IFC Files

Open any .ifc file in VSCode/VSCodium
The extension automatically activates for files with .ifc extension
All features are immediately available

Keyboard Shortcuts

Feature	Windows/Linux	macOS
Go to Definition	`F12`	`F12`
Find All References	`Shift+F12`	`Shift+F12`
Document Symbols	`Ctrl+Shift+O`	`Cmd+Shift+O`
Open Documentation	`Ctrl+Click`	`Cmd+Click`
Hover Information	Hover mouse	Hover mouse

Tree Views

The extension adds two tree views to the Explorer sidebar:

IFC Entity Hierarchy

Shows parent-child relationships between entities
Useful for understanding spatial structure
Example: IFCPROJECT → IFCSITE → IFCBUILDING → IFCBUILDINGSTOREY

IFC Entity References

Lists all entities with their reference counts
Helps identify heavily-used entities
Useful for quality checking

Both views include:

🔄 Refresh button to update after file changes
Click to navigate to entity definitions
Expand/collapse for better organization

Documentation Links

When you Ctrl+Click on an entity type, the extension:

Detects the schema version from your IFC file's FILE_SCHEMA line
Finds the correct documentation URL:
- IFC2X3: Uses entity-to-package mapping (e.g., IFCWALL → ifcsharedbldgelements)
- IFC4: Standard link URLs
- IFC4X3: Proper PascalCase entity names (e.g., IfcMeasureWithUnit)
Opens your browser to the official buildingSMART documentation

Example URLs:

IFC2X3: https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/ifcsharedbldgelements/lexical/ifcwall.htm
IFC4: https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/link/ifcwall.htm
IFC4X3: https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcWall.htm

Configuration

Currently, the extension works out-of-the-box with no configuration required. All IFC schema versions (IFC2X3, IFC4, IFC4X3) are automatically detected and supported.

Development

Project Structure

ifc-language-server/
├── client/
│   └── src/
│       ├── extension.ts                      # Main extension entry point
│       ├── ifcDefinitionProvider.ts          # Go to Definition (F12)
│       ├── ifcReferenceProvider.ts           # Find References (Shift+F12)
│       ├── ifcHoverProvider.ts               # Hover information
│       ├── ifcDocumentationLinkProvider.ts   # Ctrl+Click documentation
│       ├── ifcEntityHierarchyProvider.ts     # Hierarchy tree view
│       ├── ifcEntityReferencesProvider.ts    # References tree view
│       ├── ifcDocumentSymbolProvider.ts      # Document outline
│       ├── ifc2x3-mappings.txt              # IFC2X3 entity→package mapping
│       ├── ifc4x3-mappings.txt              # IFC4X3 entity→PascalCase mapping
│       └── generate-ifc-provider-FINAL.py   # Regenerate doc provider
├── syntaxes/
│   └── ifc.tmLanguage.json                  # TextMate syntax highlighting
├── package.json                              # Extension manifest
└── README.md                                 # This file

Updating Documentation Mappings

If buildingSMART updates their documentation structure, regenerate the mappings:

cd client/src

# For IFC2X3 (if URL structure changes)
curl -s "https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/alphabeticalorder_entities.htm" > ifc2x3-page.html
grep -E 'HREF="[^"]+/lexical/[^"]+"' ifc2x3-page.html | \
  sed 's/.*HREF="\([^/]*\)\/lexical\/\([^"]*\)\.htm".*/\1 \2/' | \
  awk '{print toupper($2), $1}' | \
  sort -u > ifc2x3-mappings.txt

# For IFC4X3 (if entities are added)
curl -s "https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/annex-b1.html" > annex-b1.html
grep -oE 'href="[^"]*lexical/Ifc[^"]*\.htm"' annex-b1.html | \
  sed 's/.*lexical\///' | \
  sed 's/\.htm.*//' | \
  sort -u > ifc4x3-entities.txt
awk '{print toupper($0), $0}' ifc4x3-entities.txt > ifc4x3-mappings.txt

# Regenerate the TypeScript provider
python3 generate-ifc-provider-FINAL.py ifc2x3-mappings.txt ifc4x3-mappings.txt > ifcDocumentationLinkProvider.ts

# Recompile
cd ../..
npm run compile

Building for Distribution

# Install VSCE (once)
npm install -g vsce

# Package the extension
vsce package

# This creates: ifc-language-server-X.Y.Z.vsix

Testing

Press F5 to launch Extension Development Host
Open a test IFC file (e.g., test.ifc)
Test each feature:
- Hover over entity references
- F12 on references
- Shift+F12 for references
- Ctrl+Click on entity types
- Open tree views
- Check syntax highlighting

Supported IFC Schemas

✅ IFC2X3 - Full support (653 entities)
✅ IFC4 - Full support
✅ IFC4X3 - Full support (876 entities)

The extension automatically detects the schema version from the FILE_SCHEMA line in your IFC file.

Known Limitations

Large IFC files (>10MB) may experience slower hover/navigation performance
The extension reads the entire file into memory - very large files (>100MB) may impact VSCode/VSCodium performance
Documentation links require an internet connection to open buildingSMART pages

Troubleshooting

Extension not activating

Ensure the file has .ifc extension
Check VSCode/VSCodium's Output panel (select "IFC Language Server" from dropdown) for errors
Try reloading VSCode/VSCodium: Ctrl+Shift+P → "Reload Window"

Go to Definition not working

Ensure the entity reference format is correct: #123
Check that the referenced entity exists in the file
The entity definition must be in the format: #123 = IFCENTITYTYPE(...)

Documentation links opening wrong pages

Verify your IFC file has a valid FILE_SCHEMA line
Check that the entity type is spelled correctly
Some rare entities may not have documentation pages

Tree views not updating

Click the 🔄 Refresh button at the top of the tree view
If still not updating, close and reopen the IFC file

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Areas for Contribution

Support for additional IFC schemas (IFC4.1, IFC4.2, etc.)
Performance optimizations for large files
Additional language features (auto-completion, validation, etc.)
Better syntax highlighting rules
Internationalization/localization

Acknowledgments

This extension was inspired by and builds upon concepts from ifc-developer-tools by Alan Rynne.

Special thanks to:

Alan Rynne for the foundational IFC parsing and VSCode extension concepts
buildingSMART International for IFC schema documentation and standards
The open-source community supporting IFC tooling development

License

MIT License - see LICENSE file for details.

This project builds upon concepts from ifc-developer-tools, which is also MIT licensed.

Support

🐛 Report bugs & Feature requests: https://hub.openingdesign.com/OpeningDesign/ifc-language-server/issues

Enjoy working with IFC files in VSCode/VSCodium! 🏗️

11 KiB Raw Permalink Blame History