{"_id":"@alexgao5417/pathflow","name":"@alexgao5417/pathflow","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.2":{"name":"@alexgao5417/pathflow","version":"0.0.2","description":"Animated flow rendering for Deck.gl and standalone maps.","type":"module","scripts":{"test:e2e":"node --test ./e2e/*.test.mjs"},"main":"./src/index.ts","module":"./src/index.ts","exports":{".":"./src/index.ts","./advanced":"./src/advanced.ts","./demo":"./src/demo/index.ts"},"keywords":["deckgl","deck.gl","mapbox","geojson","traffic","flow","pathflow","animation","visualization"],"license":"MIT","_id":"@alexgao5417/pathflow@0.0.2","gitHead":"da9fa3744fc916c071377e6b98825139bf00224d","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-EEQe/mgTrH5RFi5jepWALDqFQJpZ/Joay4o1EWL6voP0tpNeQeNQxPMfhXSIUZk5PWfER7cFNuUHlkcp3OVF0w==","shasum":"b80758945954bb871ba768a248ce8c65a31e9a81","tarball":"https://registry.npmjs.org/@alexgao5417/pathflow/-/pathflow-0.0.2.tgz","fileCount":23,"unpackedSize":107540,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIG2grTud2F72jOf7Z/APgGZ2+CNBnwrtMgb60Bou8/aNAiAVwO7TqmVkfHMvnHQn+6jZIRVNI3V9BxoXWKECI1iZ1Q=="}]},"_npmUser":{"name":"alexgao5417","email":"gcy541752099@gmail.com"},"directories":{},"maintainers":[{"name":"alexgao5417","email":"gcy541752099@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pathflow_0.0.2_1774780294795_0.9507108183903492"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T10:31:34.653Z","0.0.2":"2026-03-29T10:31:34.944Z","modified":"2026-03-29T10:31:35.214Z"},"maintainers":[{"name":"alexgao5417","email":"gcy541752099@gmail.com"}],"description":"Animated flow rendering for Deck.gl and standalone maps.","keywords":["deckgl","deck.gl","mapbox","geojson","traffic","flow","pathflow","animation","visualization"],"license":"MIT","readme":"# pathflow\n\n`pathflow` animates particles or small mesh entities along GeoJSON line data in Deck.gl and standalone maps.\n\nThe package is organized around two primary entry points:\n\n1. `usePathflow(...)`\n   Use this when you already have your own `DeckGL` map.\n2. `StandalonePathflowMap`\n   Use this when you want a ready-made map component.\n\nAdvanced helpers are still available from `pathflow/advanced`, but most users should start with the two APIs above.\n\n## Install\n\n```bash\nnpm install pathflow\n```\n\n## Data Requirements\n\nYour data must be line-based:\n\n- a GeoJSON `FeatureCollection`, or\n- an array of GeoJSON features\n\nSupported geometry types:\n\n- `LineString`\n- `MultiLineString`\n\nEach feature must provide either:\n\n- a single numeric value, or\n- a time series of numeric values\n\nBy default, if you do not provide custom accessors:\n\n- category comes from `properties.link_type`, then `properties.category`\n- direction comes from `properties.direction`\n- a static value comes from `value`, `volume`, `count`, or `total`\n- a time series comes from keys like `hour_0`, `hour_1`, `hour_2`, and so on\n\nThe package does not ship opinionated category presets for your data.\nIf you want per-category colors, widths, radii, or speeds, pass them through `prepareOptions.styleMap`.\n\n## Primary API\n\n### `usePathflow(options)`\n\nThis is the main facade hook for existing Deck.gl apps.\n\n`useDeckglPathflow(...)` is also exported if you want the Deck.gl-specific name, but `usePathflow(...)` is the primary API.\n\nIt handles:\n\n- preprocessing\n- optional timeline state\n- layer creation\n- summary stats\n\n#### Required input\n\n- one of:\n  - `data`\n  - `preparedData`\n\n#### Optional input\n\n- `prepareOptions`\n  Passed to preprocessing when you provide raw `data`.\n- `currentTime`\n  Controlled timeline position. If omitted, the hook uses its internal timeline state.\n- `autoPlay`\n  Defaults to `true`.\n- `initialTime`\n  Defaults to `0`.\n- `loop`\n  Defaults to `true`.\n- `stepsPerSecond`\n  Defaults to `0.35`.\n- `renderMode`\n  `\"auto\"`, `\"particles\"`, or `\"entities\"`. Defaults to `\"auto\"`.\n- `viewState`\n  Used for zoom-aware entity switching and sizing. `usePathflow(...)` also infers 2D vs 3D from `viewState.pitch`, because the user owns the map.\n- `speedMultiplier`\n  Multiplies movement speed. Defaults to `1`.\n- `particleMinPixels`\n  Minimum visible particle size.\n- `particleMaxPixels`\n  Maximum visible particle size.\n- `entityRenderer`\n  Optional mesh rendering config:\n\n```ts\n{\n  mesh: any;\n  zoomThreshold?: number;\n  maxPixelSize?: number;\n  enabledIn2D?: boolean;\n  material?: Record<string, unknown>;\n}\n```\n\n#### Returns\n\n```ts\n{\n  currentTime: number;\n  hasTimeSeries: boolean;\n  layers: any[];\n  preparedData: PreparedFlowData | null;\n  stats: {\n    activeCount: number;\n    activeLinks: number;\n    clockLabel: string | null;\n    currentStepIndex: number;\n    hasTimeSeries: boolean;\n    totalValue: number;\n  };\n  timeline: {\n    currentTime: number;\n    hasTimeSeries: boolean;\n    isPlaying: boolean;\n    pause: () => void;\n    play: () => void;\n    setTime: (time: number) => void;\n    stepCount: number;\n    toggle: () => void;\n  };\n  usingEntities: boolean;\n  validation: FlowValidationResult | null;\n}\n```\n\n#### Example\n\n```jsx\nimport DeckGL from \"@deck.gl/react\";\nimport { StaticMap } from \"react-map-gl\";\nimport { usePathflow } from \"pathflow\";\n\nexport function TrafficMap({ data, viewState }) {\n  const flow = usePathflow({\n    data,\n    viewState,\n    prepareOptions: {\n      particleDivisor: 1000,\n      entityDivisor: 1000,\n      styleMap: {\n        motorway: {\n          lineColor: \"#ffe394\",\n          particleColor: \"#ff6d43\",\n          speed: 0.26,\n        },\n      },\n    },\n  });\n\n  return (\n    <>\n      <DeckGL controller layers={flow.layers} viewState={viewState}>\n        <StaticMap mapboxApiAccessToken={MAPBOX_TOKEN} />\n      </DeckGL>\n\n      <div>{flow.stats.clockLabel}</div>\n      <div>{flow.stats.activeLinks}</div>\n      <div>{flow.stats.activeCount}</div>\n    </>\n  );\n}\n```\n\n### `StandalonePathflowMap`\n\nThis is the ready-made component for users who do not want to build their own `DeckGL` wrapper.\n\n#### Required input\n\n- `mapboxAccessToken`\n- one of:\n  - `data`\n  - `preparedData`\n\n#### Optional input\n\n- `prepareOptions`\n  Passed to preprocessing when raw `data` is used.\n- `currentTime`\n  Controlled timeline position.\n- `mapMode`\n  `\"2d\"` or `\"3d\"`. Defaults to `\"2d\"`.\n- `renderMode`\n  `\"auto\"`, `\"particles\"`, or `\"entities\"`. Defaults to `\"auto\"`.\n- `entityRenderer`\n  Same shape as `usePathflow(...)`.\n- `speedMultiplier`\n  Defaults to `1`.\n- `mapStyle`\n  Mapbox style URL.\n- `viewState`\n  Controlled view state.\n- `initialViewState`\n  Uncontrolled initial view state.\n- `fitOnDataChange`\n  Defaults to `true`.\n- `onViewStateChange(viewState)`\n- `onStatsChange(stats)`\n- `controller`\n  Custom Deck.gl controller options.\n- `id`\n- `className`\n- `style`\n\n#### Returns\n\n- a React component\n- stats are reported through `onStatsChange(...)`\n- view state changes are reported through `onViewStateChange(...)`\n\n#### Example\n\n```jsx\nimport { StandalonePathflowMap } from \"pathflow\";\n\nexport function FlowMap({ data, currentTime }) {\n  return (\n    <StandalonePathflowMap\n      currentTime={currentTime}\n      data={data}\n      mapMode=\"3d\"\n      mapboxAccessToken={MAPBOX_TOKEN}\n      prepareOptions={{\n        particleDivisor: 1000,\n        entityDivisor: 1000,\n      }}\n      style={{ height: 640 }}\n    />\n  );\n}\n```\n\n## Main Input Customization\n\n### `prepareOptions`\n\nThis is the main place where you customize how raw GeoJSON is interpreted.\n\nMost useful options:\n\n- `getValue(feature, featureIndex)`\n- `getTimeSeries(feature, featureIndex)`\n- `getCategory(feature, featureIndex)`\n- `getDirection(feature, featureIndex)`\n- `getFeatureId(feature, featureIndex)`\n- `styleMap`\n- `defaultStyle`\n- `getStyle(feature, context)`\n- `particleDivisor`\n- `entityDivisor`\n- `maxParticlesPerFeature`\n- `maxEntitiesPerFeature`\n- `sampleStepFactor`\n- `minSampleStep`\n- `timeSteps`\n- `validationMode`\n- `onWarning(warning)`\n\n### `styleMap`\n\nUse `styleMap` to customize line and particle styling by category.\n\nThe keys in `styleMap` must match whatever your `getCategory(...)` function returns.\nThey are not GeoJSON-standard values.\n\nSupported style fields:\n\n- `key`\n- `lineColor`\n- `lineOpacity`\n- `lineWidth`\n- `particleColor`\n- `particleRadius`\n- `entityColor`\n- `speed`\n\nExample:\n\n```jsx\nconst flow = usePathflow({\n  data,\n  viewState,\n  prepareOptions: {\n    getCategory: (feature) => String(feature.properties?.road_class ?? \"default\"),\n    getValue: (feature) => Number(feature.properties?.volume ?? 0),\n    styleMap: {\n      local_road: {\n        key: \"local\",\n        lineColor: \"#1c3752\",\n        lineOpacity: 96,\n        lineWidth: 1.2,\n        particleColor: \"#8ef0ff\",\n        particleRadius: 1.6,\n        speed: 0.12,\n      },\n      highway_major: {\n        key: \"highway\",\n        lineColor: \"#ffcf70\",\n        lineOpacity: 140,\n        lineWidth: 2.4,\n        particleColor: \"#ff8c5a\",\n        particleRadius: 2.4,\n        speed: 0.28,\n      },\n    },\n  },\n});\n```\n\n## Advanced API\n\nIf you want lower-level control, import from:\n\n```ts\nimport { prepareFlowData, useFlowLayer, useFlowTimeline } from \"pathflow/advanced\";\n```\n\nAvailable advanced exports include:\n\n- `prepareFlowData(...)`\n- `validateFlowData(...)`\n- `useFlowLayer(...)`\n- `useFlowTimeline(...)`\n- `getFlowStats(...)`\n- `createFlowViewState(...)`\n- `createLowPolyVehicleMesh()`\n\nThe road-traffic preset styles used by this repo’s demo are exported from `pathflow/demo`, not from the core library API.\n\n## Recommended Starting Point\n\nIf you already have a map:\n\n- start with `usePathflow(...)`\n\nIf you need a ready-to-use map component:\n\n- start with `StandalonePathflowMap`\n\nOnly drop down to `pathflow/advanced` if you need deeper control over preprocessing, timeline state, or rendering internals.\n","readmeFilename":"README.md","_rev":"1-1f5adea813aa7ac6ca1b7205162b4b64"}