codeledge / entitree-flex Goto Github PK

View Code? Open in Web Editor NEW

47.0 3.0 3.0 229 KB

Algorithm to layout trees of variable-sized nodes, while keeping linear runtime

Home Page: https://www.npmjs.com/package/entitree-flex

HTML 1.43% JavaScript 15.52% TypeScript 83.05%

typescript trees graphs layout tree d3-visualization family-tree tree-structure

entitree-flex's Introduction

entitree-flex

This is the core package that fuels the iconic https://www.entitree.com website!

In a paper from 2013, A.J. van der Ploeg enhanced the Tidy Tree (Reingold-Tilford) algorithm to allow for variable-sized nodes, while keeping its linear runtime nature. He described the algorithm in his paper, Drawing Non-layered Tidy Trees in Linear Time. The author also provided a working Java application on GitHub at https://github.com/cwi-swat/non-layered-tidy-trees

This package take it to the next level by allowing also side nodes, very useful if you are drawing family trees and pedigrees.

Examples

Install

npm i entitree-flex

yarn add entitree-flex

It does come with TS definitions

Usage from flat object

const { layoutFromMap } = require("entitree-flex")
//or
import { layoutFromMap } from "entitree-flex"

const flatTree = {
  1: {
    name: "root",
    width: 14,
    children: [2, 3],
    parents: [7]
  },
  2: { name: "child2" },
  3: { name: "child3", children: [4, 5], spouses: [6] },
  4: { name: "grandChild4" },
  5: { name: "grandChild5" },
  6: { name: "spouse of child 3" },
  7: { name: "parent of root" },
};

const { map, maxBottom, maxLeft, maxRight, maxTop, nodes, rels } = layoutFromMap(1, flatTree [, settings])

Playground

You can play live in your browser with random trees or make your own tree for testing.

Just run yarn browser and then open the file playground/index.html in your broser and see the results.

Edit the playground/source.js file to see changes.

Settings

Structure and defaults of the settings

defaultSettings = {
  clone: false, // returns a copy of the input, if your application does not allow editing the original object
  enableFlex: true, // has slightly better perfomance if turned off (node.width, node.height will not be read)
  firstDegreeSpacing: 15, // spacing in px between nodes belonging to the same source, eg children with same parent
  nextAfterAccessor: "spouses", // the side node prop used to go sideways, AFTER the current node
  nextAfterSpacing: 10, // the spacing of the "side" nodes AFTER the current node
  nextBeforeAccessor: "siblings", // the side node prop used to go sideways, BEFORE the current node
  nextBeforeSpacing: 10, // the spacing of the "side" nodes BEFORE the current node
  nodeHeight: 40, // default node height in px
  nodeWidth: 40, // default node width in px
  orientation: "vertical", // "vertical" to see parents top and children bottom, "horizontal" to see parents left and
  rootX: 0, // set root position if other than 0
  rootY: 0, // set root position if other than 0
  secondDegreeSpacing: 20, // spacing in px between nodes not belonging to same parent eg "cousin" nodes
  sourcesAccessor: "parents", // the prop used as the array of ancestors ids
  sourceTargetSpacing: 10, // the "vertical" spacing between nodes in vertical orientation, horizontal otherwise
  targetsAccessor: "children", // the prop used as the array of children ids
};

Similar examples in javascript

https://github.com/d3/d3-hierarchy no bidirectional, no flexible, no side nodes
https://github.com/Klortho/d3-flextree no bidirectional, no side nodes

License

GNU General Public License v3.0

entitree-flex's People

Contributors

Stargazers

Watchers

Forkers

badr33quest venryx voidit

entitree-flex's Issues

Fix spouses placement not as a child with shift but a close neighbour, and do not add to source node apportion

Some nodes are cut off at the edges

Next before nodes are "sometimes" off

Maybe the centerSourceToTargets is not doing its job

Opportunity to use it as d3 plugin?

This is a awesome project which provide alternative layout to d3 hierarchy! Is there any opportunity to use it as d3 plugin? I'm trying to use entitree with d3 to provide node collapse expand animation, can it be done?

Thanks!

Clarification on license

Hello. This library looks very interesting, and a good fit for a UI rework I'm attempting for my MIT-licensed Debate Map project: https://github.com/debate-map/app

My project currently has a "naive" layout approach, which is not as "compact" as I would like, when the user has expanded to a deep path in the tree. To solve this, I attempted to write my own layout algorithm, which I've been working on the past several days. I got it "mostly working" how I wanted, but it has been a pain to deal with the various remaining details/"edge cases", hence my doing another search for prior work on the subject.

I eventually came across the "Reingold–Tilford tidy algorithm", which was close to what I wanted, except it didn't seem to have handling for "non-layered" trees, ie. trees where some boxes are of different widths and heights than others in that "layer"/depth-level. Further searching eventually led me to the Drawing Non-layered Tidy Trees in Linear Time paper by A.J. van der Ploeg, which is a variant of the Tilford algorithm that seems suitable for my requirements. I especially liked that the paper linked to a public-domain implementation of the algorithm, making integration in one's own programs much easier.

But since my program is in TypeScript rather than Java, I then thought I'd see if I could find a TS/JS implementation instead -- with that search leading me here (as well as the d3-flextree package).

However, my one concern with this library is that it appears to have no license text? (there is no LICENSE file, as most GitHub repos contain)

I'm concerned that if I start using this library, but then need to make modifications to it, that it would then place my project in an "unclear" licensing state, due to using code that does not match the MIT-licensing used by the rest of the program.

So I was hoping there could be some clarification on what the licensing terms for this package are (ideally as a predefined license, though even a general statement about what usages are allowed would be preferred).

Thank you!