DOCSEARCHbyAlgolia
Submit Docs

Obsidian 3D Graph

repository·master·Indexed 18 days ago

https://github.com/alexw00/obsidian-3d-graph

A community plugin for Obsidian (version 1.0.5) that provides a three-dimensional visualization of a user's vault graph. Built with TypeScript and powered by D3.js, it allows users to render global and local graphs, configure visual parameters via DisplaySettings, manage visibility filters, and categorize nodes using GroupSettings with tag or path-based queries.

Tokens
3.2K
Snippets
15
Records
18
Agent score
63%

What's inside Obsidian 3D Graph

  2. Understand the project structure

    master

    The project is organized into several functional directories within src/:

    • src/graph/: Contains the core graph data structures and algorithms.
    • src/settings/: Manages settings data structures.
    • src/utils/: Contains shared utility functions.
    • src/views/: Contains the UI layer, further subdivided into:
      • atomics/: Small, atomic UI components.
      • graph/: Components specifically for rendering the graph.
      • settings/: Components for the settings interface.
    • src/main.ts: The main entry point for the Obsidian plugin.

  4. How NodeGroup queries match nodes

    master

    The NodeGroup.matches(query, node) method determines if a specific node belongs to a group based on the provided query string. The matching logic follows two patterns:

    1. Tag Matching: If the query starts with tag: or tag:#, the system checks if the node's tags include the string following that prefix. For example, tag:#project matches a node with the tag #project.
    2. Path Matching: If the query does not match the tag pattern, it is treated as a path prefix. The query is passed through sanitizeQuery (which removes leading ./ if present) and checked against the node's file path using startsWith.

    Query Sanitization Rules:

    • Leading ./ is stripped from the query before path matching occurs.
    // Example of tag matching logic
NodeGroup.matches("tag:#important", node); 

// Example of path matching logic
NodeGroup.matches("./notes/daily", node); // matches nodes in 'notes/daily'"

  5. Access the underlying ForceGraph3DInstance

    master

    If you need to interact directly with the underlying 3d-force-graph engine (to access low-level D3-force properties or specific 3d-force-graph methods), you can retrieve the raw instance using getInstance().

    const rawInstance = forceGraph.getInstance();
// rawInstance is of type ForceGraph3DInstance

  6. Configure FilterSettings for the 3D Graph

    master

    The FilterSettings class manages visibility filters for the 3D graph. It controls whether orphan nodes (nodes without connections) and attachment files are rendered in the visualization.

    Properties:

    • doShowOrphans (boolean): Determines if nodes with no incoming or outgoing links are displayed. Defaults to true.
    • doShowAttachments (boolean): Determines if attachment files are displayed in the graph. Defaults to false.

    You can instantiate this class directly via the constructor or reconstruct it from a stored configuration object using fromStore().

    // Direct instantiation
const settings = new FilterSettings(true, true);

// Reconstructing from a stored object (e.g., from Obsidian settings storage)
const storedData = { doShowOrphans: false, doShowAttachments: true };
const settingsFromStore = FilterSettings.fromStore(storedData);

// Exporting settings back to a plain object for storage
const configObject = settings.toObject();

  9. Configure node groups with GroupSettings and NodeGroup

    master

    The GroupSettings class manages a collection of NodeGroup objects used to categorize and color nodes in the 3D graph. Each NodeGroup is defined by a query (used to match nodes) and a color (the color applied to matched nodes).

    To create settings manually, instantiate GroupSettings with an array of NodeGroup instances.

    const settings = new GroupSettings([
  new NodeGroup("tag:#work", "#ff0000"),
  new NodeGroup("./folder/subfolder", "#00ff00")
]);

  11. Manage ForceGraph dimensions

    master

    The ForceGraph class provides methods to manually adjust the size of the 3D rendering area. This is useful when the container element changes size (e.g., window resizing or layout shifts).

    • updateDimensions(): Automatically calculates the new width and height based on the rootHtmlElement's offsetWidth and offsetHeight and applies them to the graph instance.
    • setDimensions(width, height): Directly sets the graph instance width and height to the provided numeric values.
    // Example of updating dimensions
forceGraph.updateDimensions();

// Example of setting specific dimensions
forceGraph.setDimensions(800, 600);

  12. Configure visual parameters with DisplaySettings

    master

    The DisplaySettings class manages the visual properties of the 3D graph. You can instantiate it with specific values for node size, link thickness, particle size, and particle count. It also provides utility methods for hydrating settings from a data store or exporting them as a plain object.

    // Manual instantiation
const settings = new DisplaySettings(10, 2, 5, 10);

// Hydrating from a store object
const store = { nodeSize: 8, linkThickness: 3 };
const settingsFromStore = DisplaySettings.fromStore(store);

// Exporting to a plain object for serialization
const configObject = settings.toObject();