plebeiangraphlibrary 1.0.6

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Code of Conduct for Plebeian Graph Library (PGL)
+
+## My Pledge
+In the interest of fostering an open and welcoming environment, I, as the maintainer and primary contributor of the Plebeian Graph Library (PGL), pledge to make participation in this project a harassment-free experience for everyone, regardless of individual differences.
+
+## Standards
+
+Behavior that contributes to a positive environment includes:
+
+- Using welcoming and inclusive language
+- Showing respect for differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Demonstrating empathy towards other community members
+
+Unacceptable behavior includes:
+
+- Use of sexualized language or imagery, unwelcome sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct deemed inappropriate in a professional setting
+
+## Responsibilities
+
+As the project maintainer, I am responsible for clarifying the standards of acceptable behavior and will take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+I have the right to remove, edit, or reject comments, commits, code, and other contributions that do not align with this Code of Conduct.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, as well as in public spaces when an individual is representing the project or its community. Representation of the project may include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at online or offline events.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting me [at](indrajeet.haldar08@gmail.com). All complaints will be reviewed and investigated and will result in a response that is necessary and appropriate to the circumstances. Confidentiality will be maintained for the reporter of an incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

package/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to Plebeian Graph Library (PGL)
+
+First off, thank you for considering contributing to PGL! It's people like you that make the open source community such a great place. Here are some guidelines to help you get started.
+
+## How to Contribute
+### Reporting Issues
+
+If you find a bug or have a suggestion for a new feature or enhancement, I would love to hear about it! Before you submit an issue, please check to make sure it hasn't already been reported. Here's how you can report an issue:
+
+- Go to the Issues section of our GitHub repository.
+- Click on 'New Issue'.
+- Write a clear title and a detailed description. For bugs, it's helpful to include:
+    * Steps to reproduce
+    * Expected and actual behavior
+    * Screenshots or error messages
+    * Your environment (browser, OS, etc.)
+
+### Submitting Changes
+
+Changes are accepted via Pull Requests (PRs) on GitHub. Here’s how you make a PR:
+
+1. Fork the PGL repository.
+1. Clone your fork to your local machine.
+1. Create a new branch.
+1. Make your changes. Please keep your code as clean and well-organized as possible.
+1. Test your changes.
+1. Commit your changes. Write a clear, descriptive commit message.
+1. Push your changes to your fork on GitHub.
+1. From your fork, make a Pull Request to the PGL main branch.
+1. In your pull request, describe what your changes do and mention any relevant issue numbers.
+
+Please adhere to the coding conventions used throughout the project (indentation, accurate comments, etc.).
+
+### Seeking Support
+
+If you need help or have any questions about contributing, please open an issue in the GitHub Issues. I'd be happy to help!
+
+### Improving Documentation
+
+Good documentation is as important as the code itself. If you find errors, typos, or areas that need enhancement, feel free to create a pull request.
+
+## Code of Conduct
+
+Please follow Code of Conduct in all your interactions with the project.
+
+## Pull Request Process
+
+1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
+1. Update the README.md with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations, and container parameters.
+1. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme used is SemVer.
+1. The Pull Request will be merged once it is approved and passes CI checks. 
+

package/Examples/1_ZKC_simple.html

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <link rel="stylesheet" href="MasterStyle.css">
+  <title>ZKC3d - Example</title>
+</head>
+
+<body>
+  <h4>A simple plot of the ZKC Dataset <a href="https://github.com/range-et/PGL/blob/main/public/1_ZKC_simple.html">Code</a></h4>
+  <canvas id="displayCanvas" class="displayCanvas"></canvas>
+  <script type="module">
+    // import the library
+    import * as PGL from "../Build/pgl_module.js";
+
+    // construct a simple ZKC graph
+    // this graph is pre initialized (Since it is simulated in this case)
+    const zkcSimulated = await PGL.SampleData.LoadZKCSimulated();
+    // console log this to see how this data is stored 
+    console.log(zkcSimulated);
+    // also as a reference just see how this data is stored 
+    zkcSimulated.printData();
+
+    // set the width and height 
+    const width = 800;
+    const heigth = 700;
+
+    // pass in the graph and the canvas into the drawing object to draw it
+    // first get the canvas element
+    const canvas = document.getElementById("displayCanvas");
+    // then create a graph drawer object
+    // to do that first make a options object
+    const graphDrawerOptions = {
+      graph: zkcSimulated,
+      width: width,
+      height: heigth,
+      canvas: canvas
+    };
+    // then create the visualization window
+    // with those settings
+    const graph3d = new PGL.GraphDrawer.GraphDrawer3d(graphDrawerOptions);
+    // initialize this object before adding things to it 
+    await graph3d.init();
+
+    // Create the 3d elements for the graph
+    // first describe a global scaling factor
+    const bounds = 1
+    // first create all the node elements
+    const nodeVisualElements = PGL.ThreeWrapper.DrawTHREEBoxBasedVertices(zkcSimulated, bounds, 0xffffff, 5);
+    // add the node elements to the scene
+    graph3d.addVisElement(nodeVisualElements);
+    // then create the edge elements 
+    const edgeVisualElements = PGL.ThreeWrapper.DrawTHREEGraphEdgesThick(zkcSimulated, bounds, 0xffafcc, 0.02);
+    graph3d.addVisElement(edgeVisualElements);
+
+    // then there are two last steps for a 3d graph
+    // this is done so that other 3d objects can be added in later
+    // since the base library is three.js all standard three js things are possible
+    // now moving on to the two steps :
+    // make an animation function
+    function animate() {
+      requestAnimationFrame(animate);
+      graph3d.rendercall();
+    }
+
+    // append the graph renderer to the container
+    // and then drawing render calls
+    animate();
+
+  </script>
+</body>
+
+</html>

package/Examples/2_ZKC_edge_bundling.html

@@ -0,0 +1,82 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="stylesheet" href="MasterStyle.css">
+    <title>ZKC3d - Example</title>
+</head>
+
+<body>
+    <h4>A simple plot of the ZKC Dataset <a href="https://github.com/range-et/PGL/blob/main/public/2_ZKC_edge_bundling.html">Code</a></h4>
+    <canvas id="displayCanvas" class="displayCanvas"></canvas>
+    <script type="module">
+        // import the library
+        import * as PGL from "../Build/pgl_module.js";
+
+        // construct a simple ZKC graph
+        // this graph is pre initialized (Since it is simulated in this case)
+        const zkcSimulated = await PGL.SampleData.LoadZKCSimulated();
+        // console log this to see how this data is stored 
+        zkcSimulated.printData();
+
+        // set the width and height 
+        const width = 800;
+        const heigth = 700;
+
+        // pass in the graph and the canvas into the drawing object to draw it
+        // first get the canvas element
+        const canvas = document.getElementById("displayCanvas");
+        // then create a graph drawer object
+        // to do that first make a options object
+        const graphDrawerOptions = {
+            graph: zkcSimulated,
+            width: width,
+            height: heigth,
+            canvas: canvas
+        };
+        // then create the visualization window
+        // with those settings
+        const graph3d = new PGL.GraphDrawer.GraphDrawer3d(graphDrawerOptions);
+        // initialize this object before adding things to it 
+        await graph3d.init();
+
+        // Create the 3d elements for the graph
+        // first describe a global scaling factor
+        const bounds = 1
+        // first create all the node elements
+        const nodeVisualElements = PGL.ThreeWrapper.DrawTHREEBoxBasedVertices(zkcSimulated, bounds, 0xffffff, 3);
+        // add the node elements to the scene
+        graph3d.addVisElement(nodeVisualElements);
+
+        const EdgeMap = zkcSimulated.get_edge_map();
+        const EdgeMap_copy = PGL.Drawing.DisplaceEdgeInY(EdgeMap, 20);
+        const newEdgeMap = await PGL.Drawing.DrawEdgeBundling(EdgeMap_copy, 50, 10);
+        // then create the edge elements 
+        // these are the reuglar edges 
+        const edgeVisualElements = PGL.ThreeWrapper.DrawThinEdgesFromEdgeMap(EdgeMap, bounds, 0x62b6cb, 0.01);
+        graph3d.addVisElement(edgeVisualElements);
+        // these are the bundled edges 
+        const edgeVisualElements_Bundled = PGL.ThreeWrapper.DrawThickEdgesFromEdgeMap(newEdgeMap, bounds, 0x5fa8d3, 0.01);
+        graph3d.addVisElement(edgeVisualElements_Bundled);
+
+        // then there are two last steps for a 3d graph
+        // this is done so that other 3d objects can be added in later
+        // since the base library is three.js all standard three js things are possible
+        // now moving on to the two steps :
+        // make an animation function
+        function animate() {
+            requestAnimationFrame(animate);
+            graph3d.rendercall();
+        }
+
+        // append the graph renderer to the container
+        // and then drawing render calls
+        animate();
+
+    </script>
+</body>
+
+</html>

package/Examples/3_LargePointCloud.html

@@ -0,0 +1,82 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <link rel="stylesheet" href="MasterStyle.css" />
+  <title>Large Graph - Example</title>
+</head>
+
+<body>
+  <h4>A large plot using PGL - 5000 points <a href="https://github.com/range-et/PGL/blob/main/public/3_LargePointCloud.html">Code</a></h4>
+  <canvas id="displayCanvas" class="displayCanvas"></canvas>
+  <script type="module">
+    // import the library
+    import * as PGL from "../Build/pgl_module.js";
+
+    // create an Erdos Reyni graph. Lets do 1000 Points for this example
+    const G = await PGL.Models.GenerateErdosReyni_n_p(5000, 0.0001);
+    // since these graphs can be really large - they are not initialized 
+    // so you must initialize them
+    G.initialize();
+    G.printData();
+    
+    // now in this case we shall use the Kamada Kawai algorithm to initilaize all the positions
+    const simulatedPosMap = await PGL.Drawing.SimulateKamadaKawai(G, 2);
+    G.apply_position_map(simulatedPosMap);
+    // get the line map associated 
+    const lmap = PGL.Drawing.DrawEdgeLinesDivisions(G, 1);
+    G.apply_edge_pos_maps(lmap)
+    
+    // set the width and height 
+    const width = 800;
+    const heigth = 700;
+
+    // pass in the graph and the canvas into the drawing object to draw it
+    // first get the canvas element
+    const canvas = document.getElementById("displayCanvas");
+    // then create a graph drawer object
+    // to do that first make a options object
+    const graphDrawerOptions = {
+      graph: G,
+      width: width,
+      height: heigth,
+      canvas: canvas
+    };
+
+    // then create the visualization window
+    // with those settings
+    const graph3d = new PGL.GraphDrawer.GraphDrawer3d(graphDrawerOptions);
+    // initialize this object before adding things to it 
+    await graph3d.init();
+
+    // Create the 3d elements for the graph
+    // first describe a global scaling factor
+    const bounds = 0.1
+    // first create all the node elements
+    const nodeVisualElements = PGL.ThreeWrapper.DrawTHREEGraphVertices(G, bounds, 1, 0xffffff, 1);
+    // add the node elements to the scene
+    graph3d.addVisElement(nodeVisualElements);
+    // then create the edge elements 
+    const edgeVisualElements = PGL.ThreeWrapper.DrawTHREEGraphEdgesThin(G, bounds, 0xffafcc, 0.01);
+    graph3d.addVisElement(edgeVisualElements);
+
+    // then there are two last steps for a 3d graph
+    // this is done so that other 3d objects can be added in later
+    // since the base library is three.js all standard three js things are possible
+    // now moving on to the two steps :
+    // make an animation function
+    function animate() {
+      requestAnimationFrame(animate);
+      graph3d.rendercall();
+    }
+
+    // append the graph renderer to the container
+    // and then drawing render calls
+    animate();
+  </script>
+</body>
+
+</html>

package/Examples/4_ToggleActivation.html

@@ -0,0 +1,106 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="stylesheet" href="MasterStyle.css" />
+    <title>Large Graph Toggle - Example</title>
+</head>
+
+<body>
+    <h4>Toggle and activate some nodes <a href="https://github.com/range-et/PGL/blob/main/public/4_ToggleActivation.html">Code</a></h4>
+    <div id="toggle">Toggle Activation</div>
+    <canvas id="displayCanvas" class="displayCanvas"></canvas>
+    <script type="module">
+        // import the library
+        import * as PGL from "../Build/pgl_module.js";
+
+        // create an Erdos Reyni graph. Lets do 1000 Points for this example
+        const G = await PGL.Models.GenerateErdosReyni_n_p(1000, 0.02);
+        // since these graphs can be really large - they are not initialized 
+        // so you must initialize them
+        G.initialize();
+        G.printData();
+
+        // now in this case we shall use the Kamada Kawai algorithm to initilaize all the positions
+        // this essentially spreads them out a little
+        const simulatedPosMap = await PGL.Drawing.SimulateKamadaKawai(G, 3, 500, 1, 1.5);
+        G.apply_position_map(simulatedPosMap);
+        // get the line map associated 
+        const lmap = PGL.Drawing.DrawEdgeLinesDivisions(G, 1);
+        G.apply_edge_pos_maps(lmap)
+
+        // set the width and height 
+        const width = 800;
+        const heigth = 700;
+
+        // pass in the graph and the canvas into the drawing object to draw it
+        // first get the canvas element
+        const canvas = document.getElementById("displayCanvas");
+        // then create a graph drawer object
+        // to do that first make a options object
+        const graphDrawerOptions = {
+            graph: G,
+            width: width,
+            height: heigth,
+            canvas: canvas
+        };
+
+        // then create the visualization window
+        // with those settings
+        const graph3d = new PGL.GraphDrawer.GraphDrawer3d(graphDrawerOptions);
+        // initialize this object before adding things to it 
+        await graph3d.init();
+
+        // Create the 3d elements for the graph
+        // first describe a global scaling factor
+        const bounds = 0.1
+        // first create all the node elements
+        const nodeVisualElements = PGL.ThreeWrapper.DrawTHREEGraphVertices(G, bounds, 3, 0xffffff, 1);
+        // now in cases of edges - this is really what slows down the whole process 
+        // A trick I use is to render sample about 10% of the lines and then draw them
+        // To do that collect all the edges (as an lmap)
+        const Edges = G.get_edge_map()
+        const EdgesToDraw = PGL.Utilities.getRandomSubset_map(Edges, 0.1);
+        const edgeVisualElements = PGL.ThreeWrapper.DrawThinEdgesFromEdgeMap(EdgesToDraw, bounds, 0x5fa8d3)
+
+        // add the node elements to the scene
+        graph3d.addVisElement(nodeVisualElements);
+        graph3d.addVisElement(edgeVisualElements);
+        // then there are two last steps for a 3d graph
+        // this is done so that other 3d objects can be added in later
+        // since the base library is three.js all standard three js things are possible
+        // now moving on to the two steps :
+        // make an animation function
+        function animate() {
+            requestAnimationFrame(animate);
+            graph3d.rendercall();
+        }
+
+        // append the graph renderer to the container
+        // and then drawing render calls
+        animate();
+
+        // lastly add a method so that everytime toggle activation is clicked the colors are randomized
+        function toggle_randomizer(){
+            // this need the child element - this probably would get fixed in a future update
+            PGL.ThreeWrapper.ResetVertexColors(nodeVisualElements.children[0]);
+            // in this case just randomly activate like 30% of the nodes 
+            const activated = [];
+            for (let i = 0; i < G.nodes.size; i++) {
+                if(Math.random()<0.3){
+                    activated.push(i)
+                }
+            }
+            // use this to change the activation thingy 
+            PGL.ThreeWrapper.ChangeTheVertexColours(nodeVisualElements.children[0], activated, 0xff0000);
+        }
+        // assign this function to the toggle button
+        document.getElementById("toggle").onclick = toggle_randomizer;
+
+    </script>
+</body>
+
+</html>

package/Examples/MasterStyle.css

@@ -0,0 +1,53 @@
+:root {
+  --skyBlue: #bee9e8;
+  --teal: #62b6cb;
+  --navy: #1b4965;
+  --lavender: #cae9ff;
+  --electricBlue: #5fa8d3;
+  --charcoal: #333533;
+  --black: #242423;
+  --yellow: #f5cb5c;
+  --cream: #e8eddf;
+  --grey: #cfdbd5;
+}
+
+* {
+  font-family: "Courier New", Courier, monospace;
+  color: var(--cream);
+}
+
+body {
+  background-color: var(--charcoal);
+  text-align: center;
+}
+
+h4 {
+  z-index: 10;
+  text-align: center;
+}
+
+main{
+  max-width: 1000px;
+  padding: 10px;
+  margin: auto;
+}
+
+.displayCanvas {
+  margin-left: auto;
+  margin-right: auto;
+  outline: var(--black) 3px solid;
+}
+
+#toggle{
+  padding: 10;
+  background-color: var(--navy);
+  max-width: 200px;
+  margin: 10px;
+  margin-left: auto;
+  margin-right: auto;
+  cursor: pointer;
+}
+
+#toggle:hover{
+  background-color: var(--teal);
+}

package/Examples/index.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="stylesheet" href="MasterStyle.css" />
+    <title>PGL Examples</title>
+</head>
+
+<body>
+    <main>
+        <h1>Here are the examples for the Plebian Graph Library:</h1>
+        <hr>
+        <h3>Example 1:</h3>
+        <p>A simple example of a simple graph - this is the ZKC dataset, this come with the library to familiarize
+            yourself with the library</p>
+        <a href="1_ZKC_simple.html">Example 1</iframe></a>
+        <hr>
+        <h3>Example 2:</h3>
+        <p>The same example but with the edge bundling, edge displacement functionalities being demonstrated</p>
+        <a href="2_ZKC_edge_bundling.html">Example 2</iframe></a>
+        <hr>
+        <h3>Example 3:</h3>
+        <p>A key feature of the library is to render really large graphs, this is an example with 5000 points. It also has some of the other features like the kamada kawai layout feature being demonstrated here. The Erdos-Reyni model is also whats used here to generate the really large graph</p>
+        <a href="3_LargePointCloud.html">Example 3</iframe></a>
+        <hr>
+        <h3>Example 4:</h3>
+        <p>Lastly, edges really slow down the rendering time associated with the visualisation, in most cases I render in batches and draw some of the edges, this example shows the edge sampling operation. Also one of the key features of the library, dynamically changing properties of the graph, for example in this case it randomly activates some of the nodes, this feature is what helps in simulating diffusion cascades on networks</p>
+        <a href="4_ToggleActivation.html">Example 4</a>
+    </main>
+</body>
+
+</html>

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Indrajeet Haldar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.