{"id":23406975,"url":"https://github.com/tkdnbb/nodegrapher","last_synced_at":"2025-10-06T11:39:02.114Z","repository":{"id":266246350,"uuid":"897805136","full_name":"tkdnbb/nodegrapher","owner":"tkdnbb","description":"A Node package for transforming images into spatial graph data.","archived":false,"fork":false,"pushed_at":"2024-12-13T04:30:56.000Z","size":1976,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-20T22:00:13.201Z","etag":null,"topics":["image-processing","opencv"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/nodegrapher","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tkdnbb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-03T09:16:51.000Z","updated_at":"2025-05-15T01:56:49.000Z","dependencies_parsed_at":"2025-04-11T22:40:31.060Z","dependency_job_id":"93abfa12-789f-4bb2-b82f-ad6aad550bdd","html_url":"https://github.com/tkdnbb/nodegrapher","commit_stats":null,"previous_names":["tkdnbb/nodegrapher"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tkdnbb/nodegrapher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkdnbb%2Fnodegrapher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkdnbb%2Fnodegrapher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkdnbb%2Fnodegrapher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkdnbb%2Fnodegrapher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tkdnbb","download_url":"https://codeload.github.com/tkdnbb/nodegrapher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkdnbb%2Fnodegrapher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276430838,"owners_count":25641123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-22T02:00:08.972Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-processing","opencv"],"created_at":"2024-12-22T14:16:39.753Z","updated_at":"2025-10-06T11:39:02.073Z","avatar_url":"https://github.com/tkdnbb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nodegrapher\n\nA TypeScript/Node.js package for transforming images into spatial graph data. This package provides utilities to extract graph structures from images, making it useful for various applications such as network analysis, path planning, and spatial data processing.\n\n## Installation\n\n```bash\nnpm install nodegrapher\n```\n\n## Features\n\n- Extract graph structures from images\n- Generate road-like graph networks\n- Optional graph visualization\n- TypeScript support\n- Flexible output formats\n\n## Usage\n\n### Basic Usage\n\n```typescript\nimport { processImageToGraph, saveRoad, extractGraphFromImage, visualizeGraph } from 'nodegrapher';\n\n// Process an image and get the full graph data (including obstacles)\nconst graphData = await processImageToGraph(\n  'path/to/image.jpg',\n  'output.json',\n  1  // maxContainCount: controls the maximum containment count for graph processing\n);\n\n// Generate and save a road graph (without obstacles)\nconst roadGraph = await saveRoad(\n  'path/to/image.jpg',  // same input image\n  'road.json'          // output path (optional, defaults to \"road.json\")\n);\n\n// To visualize a graph from an image\nconst graph = await extractGraphFromImage('path/to/image.jpg', 10, 1);\nawait visualizeGraph('path/to/image.jpg', graph, 'visualization.jpg');\n```\n\n### Function Differences\n\n- `processImageToGraph`: Extracts and saves the complete graph structure from an image, including all nodes and obstacles. This is useful when you need the full spatial data representation of the image.\n\n- `saveRoad`: Generates and saves a simplified road graph that focuses on navigable paths while excluding obstacles. This is ideal for applications like path planning where you only need the road network structure.\n\nBoth functions process the same input image but produce different outputs based on their specific purposes:\n- Full graph (processImageToGraph): Contains all spatial data including obstacles\n- Road graph (saveRoad): Contains only the road network structure, optimized for navigation\n\n- `extractGraphFromImage`: Extracts a graph structure directly from an image without saving to file. This is useful when you need to extract the graph structure for further processing or analysis.\n\n- `filterRoadNodes`: Filters out new nodes that are enclosed by any polygons formed by edges_list.\n\n![Before and After Filtering](./img/before_after.png)\n\n### CLI Usage\n\nThe package provides the following CLI commands:\n\n1. Extract graph data from an image:\n```bash\nnpm run extract -- --image_path img/example.jpg --output_path graph.json [--max_contain \u003cnumber\u003e] [--num_x \u003cnumber\u003e]\n```\n\n2. Extract road graph data from an image:\n```bash\nnpm run extract-road -- --image_path img/example.jpg [--output_path road.json] [--max_contain \u003cnumber\u003e] [--num_x \u003cnumber\u003e]\n```\n\n3. Visualize graph structure from an image:\n```bash\nnpm run visualize -- --image_path img/example.jpg [--output_path visualization.jpg] [--distance_threshold \u003cnumber\u003e] [--max_contain \u003cnumber\u003e] [--num_x \u003cnumber\u003e]\n```\n\n**Extract Command Arguments:**\n- `--image_path`: Path to the input image file\n- `--output_path`: Path where the output JSON file will be saved\n- `--max_contain` (optional): Maximum containment value for graph processing (default: 0)\n- `--num_x` (optional): Number of nodes to generate in the x direction for the road graph (default: 15)\n\n**Extract Road Command Arguments:**\n- `--image_path`: Path to the input image file\n- `--output_path` (optional): Path where the road graph JSON file will be saved (default: road.json)\n- `--max_contain` (optional): Maximum containment value for graph processing (default: 0)\n- `--num_x` (optional): Number of nodes to generate in the x direction for the road graph (default: 15)\n\n**Visualize Command Arguments:**\n- `--image_path`: Path to the input image file\n- `--output_path` (optional): Path where the visualization will be saved. If not provided, saves next to input with '_visualized' suffix\n- `--distance_threshold` (optional): Distance threshold for node connections (default: 10)\n- `--max_contain` (optional): Maximum containment value for graph processing (default: 0)\n- `--num_x` (optional): Number of nodes to generate in the x direction for the road graph (default: 15)\n\n### API Reference\n\n#### `processImageToGraph(imagePath: string, outputPath: string, maxContainCount?: number, numX?: number): Promise\u003cGraphData | undefined\u003e`\nProcesses an image to extract a graph structure and saves it to a JSON file.\n\n- `imagePath`: Path to the input image file\n- `outputPath`: Path where the graph data will be saved as JSON\n- `maxContainCount` (optional): Maximum containment value for graph processing (default: 0)\n- `numX` (optional): Number of nodes to generate in the x direction (default: 15)\n\nReturns a Promise that resolves to the graph data.\n\n#### `saveRoad(imagePath: string, outputPath?: string, maxContainCount?: number, numX?: number): Promise\u003cGraphData | undefined\u003e`\nGenerates and saves a road graph based on the provided image.\n\n- `imagePath`: Path to the input image file\n- `outputPath` (optional): Path where the road graph will be saved as JSON (default: \"road.json\")\n- `maxContainCount` (optional): Maximum containment value for graph processing (default: 0)\n- `numX` (optional): Number of nodes to generate in the x direction (default: 15)\n\nReturns a Promise that resolves to the road graph data, or undefined if no road graph could be generated.\n\n#### `extractGraphFromImage(imagePath: string, distanceThreshold?: number, maxContainCount?: number, numX?: number): Promise\u003cGraphData\u003e`\nExtracts a graph structure directly from an image without saving to file.\n\n- `imagePath`: Path to the input image file\n- `distanceThreshold` (optional): Distance threshold for node connections (default: 10)\n- `maxContainCount` (optional): Maximum containment value for graph processing (default: 0)\n- `numX` (optional): Number of nodes to generate in the x direction (default: 15)\n\nReturns a Promise that resolves to the graph data.\n\n#### `removeTextFromImage(imagePath: string, outputPath: string): Promise\u003cvoid\u003e`\nRemoves text from an image using OpenCV-based text detection.\n\n- `imagePath`: Path to the input image file\n- `outputPath`: Path where the processed image will be saved\n- Uses adaptive thresholding and contour detection to identify and remove text regions\n- Fills removed text areas with the surrounding background color\n\nReturns a Promise that resolves when the text removal is complete.\n\n#### `visualizeGraph(imagePath: string, graph: GraphData, outputPath: string): Promise\u003cvoid\u003e`\nVisualizes a graph structure on top of an image.\n\n- `imagePath`: Path to the input image file\n- `graph`: The graph data to visualize\n- `outputPath`: Path where the visualization will be saved\n\nReturns a Promise that resolves when the visualization is complete.\n\n### Types\n\n#### `GraphData`\n```typescript\ninterface GraphData {\n  nodes: Node[];\n  lines: Line[];\n  nodesList?: Node[][];\n}\n```\n\n## Development\n\nTo set up the development environment:\n\n1. Clone the repository\n2. Install dependencies: `npm install`\n3. Run tests: `npm test`\n4. Run linter: `npm run lint`\n\n### Neovim Plugin\n\nNodeGrapher also supports converting JSON graph data to ASCII representation using a Neovim plugin. Visit [NodeGrapher.nvim](https://github.com/tkdnbb/node-monorepo/tree/main/packages/nodegrapher.nvim) for more information.\n\n#### Example Usage\n\nUsing the `NodeGrapherToAscii` command in Neovim:\n\n![NodeGrapher Command](img/docs/nodegrapher.nvim_cmd.png)\n\nDisplayed graph window:\n\n![NodeGrapher Window](img/docs/nodegrapher.nvim_window.png)\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkdnbb%2Fnodegrapher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftkdnbb%2Fnodegrapher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkdnbb%2Fnodegrapher/lists"}