Skip to content

README.en.md

Latest commit

 

History

History
135 lines (91 loc) · 7.31 KB

README.en.md

File metadata and controls

135 lines (91 loc) · 7.31 KB
Raw

ECA Voyage Lab

Interactive voyage strategy laboratory for maritime Emission Control Areas

简体中文 | English

Live Demo / 在线演示

ECA Voyage Lab is a backend-free browser research workbench for visualizing China's Domestic Emission Control Areas (ECA/DECA), editing coastal routes, and recalculating zonal distance, vessel speed, fuel use, carbon emissions, and voyage cost strategies.

This project is intended for research demonstrations, education, and methodological discussion. It is not an electronic navigational chart, voyage-planning system, or maritime compliance tool. Real navigation, scheduling, fuel purchasing, and regulatory decisions must rely on competent authorities, official charts, and verified vessel data.

ECA Voyage Lab main workbench

Project scope and origin

The project grew out of an early undergraduate study by the maintainer on domestic liner speed optimization under Emission Control Area policies. That study contributed the research question, representative parameters, a discrete speed–fuel relationship, and the idea of choosing different speeds inside and outside an ECA.

This repository is not a web reproduction of the thesis and does not aim to replicate all of its constraints or numerical results. It reimplements and extends the central ideas as an interactive laboratory focused on:

  • editing and comparing research routes on a real map;
  • estimating distance inside and outside the ECA from route geometry;
  • recalculating speed, fuel use, carbon emissions, and cost in the browser;
  • exploring fuel-price spread, carbon price, schedule, and vessel-performance assumptions;
  • providing a base for route–speed comparisons, multi-objective analysis, and additional emission models.

For the detailed scope and modeling assumptions, see Model and research scope (Chinese).

Why the default saving is modest

The default four-leg route is not an untreated coastal baseline. It was manually annotated with ECA avoidance in mind, so route design has already captured part of the available economic benefit.

The “uniform speed” and “optimized strategy” views use the same default route. Their difference measures only the marginal value of choosing zonal speeds on a route that is already ECA-aware. Under the v0.1.0 balanced preset:

  • the circuit is about 3,009 nautical miles, including about 492 nautical miles inside the ECA;
  • zonal speed optimization saves roughly 0.2% relative to a uniform speed on the same route;
  • the modest percentage reflects route avoidance, schedule slack, and the selected price assumptions—it does not mean the solver is inactive.

To expose stronger strategy differences, edit the route to include more ECA distance, widen the MGO/HFO price spread, tighten the voyage schedule, or select another preset. A future comparison view is planned for original/avoidance routes × uniform/optimized speeds.

Features

  • Research visualization of China's coastal ECA, offshore control points, and inland boundary sections;
  • a Dalian–Qingdao–Shanghai–Guangzhou four-port circuit using terminal-area coordinates;
  • Haversine distance calculation and sampled ECA zoning;
  • discrete speed search from 15 to 21 knots with fuel and carbon costs;
  • uniform-speed, optimized-strategy, and emission-intensity views;
  • sensitivity analysis for MGO price, carbon price, and voyage duration;
  • in-map waypoint editing and a standalone JSON/GeoJSON route annotation tool;
  • automated model and browser checks for desktop, wide-screen, and mobile layouts.

Quick start

git clone https://github.com/SeanWong17/eca-voyage-lab.git
cd eca-voyage-lab
python3 -m http.server 8000

Open:

The basemap is loaded at runtime from OpenStreetMap, so the full map requires a network connection. The model, styles, ECA data, and Leaflet runtime are stored in the repository.

Development and tests

Node.js 18 or newer is required.

npm ci
npx playwright install chromium
npm test

Individual checks:

npm run check
npm run test:model
npm run test:browser

Browser tests load OpenStreetMap tiles. In an offline or restricted environment, run the syntax and model checks first.

Method summary

  1. Adjacent waypoints are measured with the Haversine great-circle formula.
  2. Route lines are sampled in intervals of no more than five nautical miles and classified by sample midpoint.
  3. Every port-to-port leg is divided into ECA and non-ECA decision segments.
  4. The solver selects from a discrete speed–fuel curve and minimizes fuel plus carbon cost within the total voyage duration.
  5. The uniform-speed policy selects one feasible speed on the same route and serves as the interactive comparison baseline.

The current browser model is a simplified dynamic program. It does not include port-specific arrival windows, weather and sea state, fuel-switching time, loading conditions, or navigational safety constraints.

Data and sources

  • ECA control points are primarily based on China's Ministry of Transport 2018 implementation plan, 交海发〔2018〕168号;
  • the mainland coastline is derived from Natural Earth 10m data and simplified for browser display;
  • basemap tiles come from OpenStreetMap;
  • ports and default routes are research annotations, not electronic navigational-chart routes;
  • the speed–fuel curve and default economic parameters follow the illustrative system used in the maintainer's early undergraduate research and are not current market quotes or guaranteed vessel-performance data.

More information:

The local references/ directory is ignored by Git. Thesis scans and other personal research materials are not part of the open-source distribution.

Repository layout

.github/         CI and contribution templates
assets/          Styles and bundled font files
docs/            Model, source, boundary, and research notes
route-editor/    Standalone route annotation page
src/data/        ECA, coastline, port, and route data
src/js/          Distance model, solver, rendering, and interactions
tests/           Model and browser automation checks
vendor/          Vendored browser dependencies
references/      Local research material; excluded from Git

Contributing

Contributions are welcome for data corrections, model extensions, visualization, tests, and documentation. Changes to policy coordinates, vessel parameters, or emission factors should include a verifiable source and distinguish regulatory text, engineering corrections, and research assumptions.

Please read the Contributing Guide, Code of Conduct, and Roadmap. Report security issues privately according to the Security Policy.

License

Original source code and documentation are available under the MIT License. Third-party libraries, fonts, icons, maps, and geographic datasets retain their own terms; see THIRD_PARTY_NOTICES.md and OFL.txt.