# amanchauhan-dev/ros_ws architecture

> Architecture diagram of the GitHub repository amanchauhan-dev/ros_ws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amanchauhan-dev/ros_ws
- Repository: https://github.com/amanchauhan-dev/ros_ws

## Overview

This repository is a ROS workspace for e-Yantra task4c, organized as several Python ROS packages rather than one monolith. The packages are separated by robot capability: mobile navigation, perception/shape detection, and arm manipulation. The workspace also includes multiple “versioned” and “real case” scripts, which suggests iterative development and scenario-specific task logic.

1. **Top-level architecture**
   The repo is split into five main packages: `ebot_3578`, `kc_3578`, `arm_3578`, `perp_3578`, and `shape_3578`. Each package has its own `package.xml`, `setup.py`, and test/lint scaffolding, indicating ROS-native deployment boundaries. The overall system is best drawn as a set of ROS nodes/modules communicating through ROS topics/services/actions, not as a traditional layered application.

2. **Mobile robot / navigation subsystem (`ebot_3578`)**
   This package owns the base navigation side. It contains a navigation map bundle (`map.pgm`, `map.yaml`, `map.npy`, `map_occupancy_grid.npy`) plus scripts such as `navigation.py`, `nav_v1.py`, `position_fetcher.py`, and `pgm_to_occupancy_grid.py`. Architecturally, this is the localization/navigation boundary: map assets feed navigation logic, and position/state utilities likely expose the robot’s pose for higher-level coordination.

3. **High-level integration/control package (`kc_3578`)**
   `kc_3578` contains `perception.py`, `shape_detection.py`, `navigation.py`, and `arm_manipulation.py`. This looks like the orchestration layer that ties the major subsystems together. For a diagram, treat it as the coordination boundary that consumes perception outputs, decides navigation behavior, and triggers arm actions.

4. **Arm manipulation subsystem (`arm_3578`)**
   This is the largest package and contains multiple generations of task logic: `final/`, `new/`, and `real_cases/`. Files like `final_arm_manipulation_3578.py`, `final_ferti_sol.py`, `hybrid_logic.py`, `unload_script.py`, and the `real_case*.py` scripts show that the arm behavior was developed through several strategies and task variants. The role of this package is end-effector control and task execution such as unloading, sorting, and handling fruits/fertilizer-like objects.

5. **Perception experimentation package (`perp_3578`)**
   This package contains `old/` and `new/` versions (`p1.py`, `p2.py`, `p3.py`), which strongly suggests a prototype-to-final evolution of perception logic. It likely acts as an experimental branch for vision processing or object classification before logic is consolidated into `kc_3578` and `shape_3578`.

6. **Shape detection package (`shape_3578`)**
   `shape_3578` contains `shape_v1.py` and `shape_v2.py`, which appears to isolate shape classification/detection logic. In the architecture diagram, this should sit under the perception stream, providing object labels or geometric categories to the coordinator and/or arm task planner.

7. **Data flow between subsystems**
   The main flow appears to be: environment/map inputs and robot pose into navigation, sensor/perception inputs into shape detection, and detected object/task state into arm manipulation. `kc_3578` likely sits in the middle, receiving perception outputs and commanding `ebot_3578` and `arm_3578` accordingly. The system is therefore a closed-loop robotics pipeline: sense → interpret → navigate → manipulate.

8. **Static assets and offline artifacts**
   The navigation package includes precomputed map representations (`.pgm`, `.yaml`, `.npy`). These are important architecture artifacts because they allow navigation without runtime map generation. The repository is not storing large business data or databases; its persistent artifacts are mostly robot maps and task scripts.

9. **Versioned task logic**
   The presence of directories like `final`, `new`, `real_cases`, `old`, and multiple `v1/v2/v3` files indicates that several algorithmic variants coexist. These are not separate product subsystems; they are alternative implementations or tuned versions for different competition scenarios. In a diagram, they should be shown as internal implementation branches under the arm/perception layers.

10. **Tooling and quality boundary**
    Every package includes test files for copyright, flake8, and pep257, which shows the code is intended to meet ROS/Python packaging and style constraints. The README also emphasizes no virtualenv dependency and no plotting/graphing logic, so the architecture is meant to run directly in the ROS environment with logging-based observability.

11. **How to draw the diagram**
    A good diagram would show:
    - a ROS workspace boundary containing the five packages,
    - `ebot_3578` as the navigation/map subsystem,
    - `shape_3578` and `perp_3578` as perception-related subsystems,
    - `arm_3578` as the actuation/task-execution subsystem,
    - `kc_3578` as the coordination layer linking perception, navigation, and manipulation.

12. **Overall system character**
    This is a robotics task workspace, not a general application stack. Its architecture is dominated by ROS package boundaries, map-driven navigation, perception-to-action control flow, and multiple competing implementations of the same core behaviors for competition tuning.

Main entry points: [`kc_3578/kc_3578/arm_manipulation.py`](https://github.com/amanchauhan-dev/ros_ws/blob/main/kc_3578/kc_3578/arm_manipulation.py) (Arm bridge), [`kc_3578`](https://github.com/amanchauhan-dev/ros_ws/tree/main/kc_3578) (kc_3578), [`arm_3578`](https://github.com/amanchauhan-dev/ros_ws/tree/main/arm_3578) (arm_3578), [`ebot_3578/ebot_3578/nav_map`](https://github.com/amanchauhan-dev/ros_ws/tree/main/ebot_3578/ebot_3578/nav_map) (Map bundle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["ROS workspace"]
end

subgraph group_navigation["Navigation"]
  node_ebot_3578[("ebot_3578<br/>ROS package")]
  node_ebot_map["Map bundle<br/>static nav assets"]
  node_ebot_nav["Navigation logic<br/>base control<br/>[navigation.py]"]
  node_ebot_pose["Pose fetcher<br/>state utility"]
  node_ebot_convert["Grid convert<br/>map transform"]
end

subgraph group_perception["Perception"]
  node_shape_3578["shape_3578<br/>ROS package"]
  node_shape_v1["Shape v1<br/>shape detector<br/>[shape_v1.py]"]
  node_shape_v2["Shape v2<br/>shape detector<br/>[shape_v2.py]"]
  node_perp_3578["perp_3578<br/>ROS package"]
  node_perp_old["Old vision<br/>prototype vision<br/>[p1.py]"]
  node_perp_new["New vision<br/>prototype vision<br/>[p2.py]"]
end

subgraph group_manipulation["Manipulation"]
  node_arm_3578["arm_3578<br/>ROS package"]
  node_arm_new["Arm logic<br/>manipulation logic"]
  node_arm_final["Final tasks<br/>task scripts"]
  node_arm_cases["Real cases<br/>scenario scripts"]
end

subgraph group_integration["Integration"]
  node_kc_3578["kc_3578<br/>ROS package"]
  node_kc_perception["Perception bridge<br/>orchestration<br/>[perception.py]"]
  node_kc_shape["Shape bridge<br/>orchestration<br/>[shape_detection.py]"]
  node_kc_nav["Nav bridge<br/>orchestration<br/>[navigation.py]"]
  node_kc_arm["Arm bridge<br/>orchestration"]
end

node_ebot_3578 -->|"uses"| node_ebot_map
node_ebot_map -->|"feeds"| node_ebot_convert
node_ebot_map -->|"supports"| node_ebot_nav
node_ebot_pose -->|"state for"| node_ebot_nav
node_kc_3578 -->|"coordinates"| node_kc_perception
node_kc_3578 -->|"coordinates"| node_kc_shape
node_kc_3578 -->|"coordinates"| node_kc_nav
node_kc_3578 -->|"coordinates"| node_kc_arm
node_kc_shape -->|"delegates to"| node_shape_3578
node_kc_perception -->|"delegates to"| node_perp_3578
node_shape_3578 -->|"implements"| node_shape_v1
node_shape_3578 -->|"implements"| node_shape_v2
node_perp_3578 -->|"contains"| node_perp_old
node_perp_3578 -->|"contains"| node_perp_new
node_kc_nav -->|"drives"| node_ebot_3578
node_kc_arm -->|"drives"| node_arm_3578
node_arm_3578 -->|"implements"| node_arm_new
node_arm_3578 -->|"implements"| node_arm_final
node_arm_3578 -->|"implements"| node_arm_cases
node_kc_perception -->|"informs"| node_kc_arm
node_kc_shape -->|"informs"| node_kc_arm
node_kc_nav -->|"sequencing"| node_kc_arm

click node_ebot_3578 "https://github.com/amanchauhan-dev/ros_ws/tree/main/ebot_3578"
click node_ebot_map "https://github.com/amanchauhan-dev/ros_ws/tree/main/ebot_3578/ebot_3578/nav_map"
click node_ebot_nav "https://github.com/amanchauhan-dev/ros_ws/blob/main/ebot_3578/ebot_3578/nav_map/navigation.py"
click node_ebot_pose "https://github.com/amanchauhan-dev/ros_ws/blob/main/ebot_3578/ebot_3578/nav_map/position_fetcher.py"
click node_ebot_convert "https://github.com/amanchauhan-dev/ros_ws/blob/main/ebot_3578/ebot_3578/nav_map/pgm_to_occupancy_grid.py"
click node_kc_3578 "https://github.com/amanchauhan-dev/ros_ws/tree/main/kc_3578"
click node_kc_perception "https://github.com/amanchauhan-dev/ros_ws/blob/main/kc_3578/kc_3578/perception.py"
click node_kc_shape "https://github.com/amanchauhan-dev/ros_ws/blob/main/kc_3578/kc_3578/shape_detection.py"
click node_kc_nav "https://github.com/amanchauhan-dev/ros_ws/blob/main/kc_3578/kc_3578/navigation.py"
click node_kc_arm "https://github.com/amanchauhan-dev/ros_ws/blob/main/kc_3578/kc_3578/arm_manipulation.py"
click node_shape_3578 "https://github.com/amanchauhan-dev/ros_ws/tree/main/shape_3578"
click node_shape_v1 "https://github.com/amanchauhan-dev/ros_ws/blob/main/shape_3578/shape_3578/shape_v1.py"
click node_shape_v2 "https://github.com/amanchauhan-dev/ros_ws/blob/main/shape_3578/shape_3578/shape_v2.py"
click node_perp_3578 "https://github.com/amanchauhan-dev/ros_ws/tree/main/perp_3578"
click node_perp_old "https://github.com/amanchauhan-dev/ros_ws/blob/main/perp_3578/perp_3578/old/p1.py"
click node_perp_new "https://github.com/amanchauhan-dev/ros_ws/blob/main/perp_3578/perp_3578/new/p2.py"
click node_arm_3578 "https://github.com/amanchauhan-dev/ros_ws/tree/main/arm_3578"
click node_arm_new "https://github.com/amanchauhan-dev/ros_ws/blob/main/arm_3578/arm_3578/new/final_arm_manipulation_3578.py"
click node_arm_final "https://github.com/amanchauhan-dev/ros_ws/tree/main/arm_3578/arm_3578/final"
click node_arm_cases "https://github.com/amanchauhan-dev/ros_ws/tree/main/arm_3578/arm_3578/real_cases"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ebot_3578,node_ebot_map,node_ebot_nav,node_ebot_pose,node_ebot_convert toneAmber
class node_shape_3578,node_shape_v1,node_shape_v2,node_perp_3578,node_perp_old,node_perp_new toneMint
class node_arm_3578,node_arm_new,node_arm_final,node_arm_cases toneRose
class node_kc_3578,node_kc_perception,node_kc_shape,node_kc_nav,node_kc_arm toneIndigo
```

## Components

### Navigation

Map-driven base motion and pose utilities.

- [ebot_3578](https://github.com/amanchauhan-dev/ros_ws/tree/main/ebot_3578): ROS package · Mobile base navigation package with map assets and pose utilities. · `ebot_3578`
- [Map bundle](https://github.com/amanchauhan-dev/ros_ws/tree/main/ebot_3578/ebot_3578/nav_map): static nav assets · Precomputed map representations used by navigation. · `ebot_3578/ebot_3578/nav_map`
- [Navigation logic](https://github.com/amanchauhan-dev/ros_ws/blob/main/ebot_3578/ebot_3578/nav_map/navigation.py): base control · Navigation routines for moving the robot through the workspace. · `ebot_3578/ebot_3578/nav_map/navigation.py`
- [Pose fetcher](https://github.com/amanchauhan-dev/ros_ws/blob/main/ebot_3578/ebot_3578/nav_map/position_fetcher.py): state utility · Fetches or exposes robot position/state for navigation coordination. · `ebot_3578/ebot_3578/nav_map/position_fetcher.py`
- [Grid convert](https://github.com/amanchauhan-dev/ros_ws/blob/main/ebot_3578/ebot_3578/nav_map/pgm_to_occupancy_grid.py): map transform · Converts PGM maps into occupancy grid form. · `ebot_3578/ebot_3578/nav_map/pgm_to_occupancy_grid.py`

### Perception

Vision and shape analysis components.

- [shape_3578](https://github.com/amanchauhan-dev/ros_ws/tree/main/shape_3578): ROS package · Dedicated shape detection package. · `shape_3578`
- [Shape v1](https://github.com/amanchauhan-dev/ros_ws/blob/main/shape_3578/shape_3578/shape_v1.py): shape detector · First shape detection implementation. · `shape_3578/shape_3578/shape_v1.py`
- [Shape v2](https://github.com/amanchauhan-dev/ros_ws/blob/main/shape_3578/shape_3578/shape_v2.py): shape detector · Refined shape detection implementation. · `shape_3578/shape_3578/shape_v2.py`
- [perp_3578](https://github.com/amanchauhan-dev/ros_ws/tree/main/perp_3578): ROS package · Perception experimentation package with versioned prototypes. · `perp_3578`
- [Old vision](https://github.com/amanchauhan-dev/ros_ws/blob/main/perp_3578/perp_3578/old/p1.py): prototype vision · Earlier perception prototype. · `perp_3578/perp_3578/old/p1.py`
- [New vision](https://github.com/amanchauhan-dev/ros_ws/blob/main/perp_3578/perp_3578/new/p2.py): prototype vision · Newer perception experiments and revisions. · `perp_3578/perp_3578/new/p2.py`

### Manipulation

Arm task execution and unloading logic.

- [arm_3578](https://github.com/amanchauhan-dev/ros_ws/tree/main/arm_3578): ROS package · Arm manipulation package with multiple task variants. · `arm_3578`
- [Arm logic](https://github.com/amanchauhan-dev/ros_ws/blob/main/arm_3578/arm_3578/new/final_arm_manipulation_3578.py): manipulation logic · Current arm manipulation and hybrid task logic. · `arm_3578/arm_3578/new/final_arm_manipulation_3578.py`
- [Final tasks](https://github.com/amanchauhan-dev/ros_ws/tree/main/arm_3578/arm_3578/final): task scripts · Finalized unloading, fruit sorting, and fertilizer routines. · `arm_3578/arm_3578/final`
- [Real cases](https://github.com/amanchauhan-dev/ros_ws/tree/main/arm_3578/arm_3578/real_cases): scenario scripts · Scenario-specific arm routines for real-case tuning. · `arm_3578/arm_3578/real_cases`

### Integration

Coordinator package that ties subsystems together.

- [kc_3578](https://github.com/amanchauhan-dev/ros_ws/tree/main/kc_3578): ROS package · High-level coordination package for perception, navigation, and arm control. · `kc_3578`
- [Perception bridge](https://github.com/amanchauhan-dev/ros_ws/blob/main/kc_3578/kc_3578/perception.py): orchestration · Bridges perception outputs into the control flow. · `kc_3578/kc_3578/perception.py`
- [Shape bridge](https://github.com/amanchauhan-dev/ros_ws/blob/main/kc_3578/kc_3578/shape_detection.py): orchestration · Routes shape detection results into the coordinator logic. · `kc_3578/kc_3578/shape_detection.py`
- [Nav bridge](https://github.com/amanchauhan-dev/ros_ws/blob/main/kc_3578/kc_3578/navigation.py): orchestration · Wraps or triggers navigation behavior from the coordinator. · `kc_3578/kc_3578/navigation.py`
- [Arm bridge](https://github.com/amanchauhan-dev/ros_ws/blob/main/kc_3578/kc_3578/arm_manipulation.py): orchestration · Triggers manipulation workflows from the coordinator. · `kc_3578/kc_3578/arm_manipulation.py`

## Connections

- ebot_3578 → Map bundle: uses · Navigation consumes static map artifacts.
- Map bundle → Grid convert: feeds · Map data can be converted into occupancy grids.
- Map bundle → Navigation logic: supports · Map assets support base navigation routines.
- Pose fetcher → Navigation logic: state for · Pose utilities provide position/state to navigation.
- kc_3578 → Perception bridge: coordinates · Coordinator manages perception flow.
- kc_3578 → Shape bridge: coordinates · Coordinator manages shape detection flow.
- kc_3578 → Nav bridge: coordinates · Coordinator manages navigation flow.
- kc_3578 → Arm bridge: coordinates · Coordinator manages manipulation flow.
- Shape bridge → shape_3578: delegates to · Shape bridge relies on dedicated shape detection package.
- Perception bridge → perp_3578: delegates to · Perception bridge can use experimentation outputs.
- shape_3578 → Shape v1: implements · Contains first shape detection version.
- shape_3578 → Shape v2: implements · Contains second shape detection version.
- perp_3578 → Old vision: contains · Houses earlier prototype vision code.
- perp_3578 → New vision: contains · Houses newer prototype vision code.
- Nav bridge → ebot_3578: drives · Coordinator drives the mobile base package.
- Arm bridge → arm_3578: drives · Coordinator drives arm manipulation package.
- arm_3578 → Arm logic: implements · Current manipulation logic lives in the new branch.
- arm_3578 → Final tasks: implements · Final task scripts implement completed workflows.
- arm_3578 → Real cases: implements · Real-case scripts capture scenario-specific variants.
- Perception bridge → Arm bridge: informs · Perception results inform manipulation decisions.
- Shape bridge → Arm bridge: informs · Detected shapes guide arm task selection.
- Nav bridge → Arm bridge: sequencing · Navigation outcomes can gate manipulation steps.
