# FreeCAD Ship: инструменты и применение к ECONA

Проверено и настроено **10 октября 2026**. Ship и Plot загружены в работающий
FreeCAD 1.1.4. Для его собственного Python 3.11 установлены Capytaine 3.0.0
и зависимости. Штатный FEM настроен на CalculiX 2.23 и комплектный Gmsh 4.15.0.
Проектное окружение `.venv` использует другой Python; наличие библиотеки там
само по себе не обеспечивает её доступность в FreeCAD.

Все инструменты с [заданной русской страницы](https://wiki.freecad.org/Ship_Workbench/ru)
разобраны по документации и установленному исходному коду. Русская страница
частично устарела: содержит десять пунктов, включая отсутствующий сейчас
«Контурный чертёж». Английская страница дополнена сопротивлением, а установленный
Ship содержит **16 команд**, включая посадку, назначение сетки и RAO.
Страницы ёмкости танков, нагрузки и GZ содержат TODO; для них основным техническим
источником послужил код. Учебные материалы описывают также старые диалоги,
pyxplot и Ghostscript: современный Ship использует Plot/Matplotlib, поэтому
эти старые зависимости для него не устанавливались.

## Быстрый выбор инструмента

| Задача | Инструмент | Что должно быть готово |
|---|---|---|
| Теоретический чертёж, сечения | Part: сечения; TechDraw: оформление | Проверенные поверхности и система координат |
| Объём, осадка, центр величины, площадь ватерлинии | Ship Hydrostatics | Замкнутые объёмы обоих поплавков, основная плоскость, диапазон осадок |
| Весовая нагрузка, ЦТ, посадка | Weight + Tank + LoadCondition + SinkAndTrim | Реальные массы, координаты, жидкости и уровни |
| Статическая остойчивость | Ship GZ | Замкнутая геометрия, проверенная нагрузка и равновесие |
| Волновая качка | Capytaine / Ship RAOs | Панельная сетка, равновесие, согласованные матрицы масс и жёсткости |
| Прочность набора и моста | FEM + Gmsh + CalculiX | Материалы, толщины, соединения, опоры и расчётные нагрузки |
| Сопротивление и необходимая мощность | Эмпирические методы Ship в их области; отдельная модель взаимодействия поплавков | Обводы, осадка, скорость и доказанная применимость метода |

## Все команды Ship

| Команда / название | Вход и выбор в FreeCAD | Результат и применение |
|---|---|---|
| `Ship_LoadExample` — загрузка примера | Выбрать Series 60, Wigley или их катамаранные варианты | Открывает один из четырёх комплектных FCStd. Применять для обучения и сравнения; перед изменениями сохранять рабочую копию примера |
| `Ship_CreateShip` — создание судна | Выделить **все замкнутые Solid** поплавков; задать длину между перпендикулярами Lpp, полную ширину B и проектную осадку T | Создаёт объект Ship, над которым работают остальные команды. Объём наружных обводов отличается от объёма материала обшивки |
| `Ship_AreasCurve` — строевая по шпангоутам | Ship; осадка, дифферент, число сечений | Площадь погружённого поперечного сечения вдоль X, график и Spreadsheet. Полезна для распределения объёма и контроля обводов; торцы требуют отдельной проверки |
| `Ship_Hydrostatics` — гидростатика | Ship; диапазон осадок, дифферент и число точек | Δ, смоченная площадь, MCT 1 см, XCB, площадь ватерлинии, KB, BMt, Cb/Cf/Cm; графики и таблица |
| `Ship_Weight` — вес | Геометрия груза и объект Ship; соответствующая масса/плотность | Объёмный вес кг/м³, поверхностный кг/м², линейный кг/м либо точечная масса кг. Для качки нужен также тензор инерции. ЦТ выводится из выбранной геометрии |
| `Ship_Tank` — танк | Solid **внутреннего объёма** танка и Ship | Создаёт переменную жидкую нагрузку; плотность и заполнение задаются в состоянии нагрузки. Массу стенок учитывать отдельно |
| `Ship_Capacity` — тарировка танка | Выбрать Tank; число уровней | Таблица и график «уровень–объём». Уровень 0…1 обозначает долю высоты, а не долю полного объёма |
| `Ship_LoadCondition` — состояние нагрузки | Выбрать Ship с весами и танками | Spreadsheet со списком грузов, плотностью жидкости и заполнением танков. Создавать отдельные состояния эксплуатации |
| `Ship_SinkAndTrim` — посадка и дифферент | Выбрать LoadCondition | Равновесная осадка и дифферент; визуализация ватерлинии, положения корпуса, ЦТ и центра величины |
| `Ship_GZ` — диаграмма статической остойчивости | LoadCondition; диапазон крена и число точек; возможность изменения дифферента | GZ, осадка и дифферент при крене; график и Spreadsheet. Жидкость меняет форму при наклонении; проверить равновесие и сходимость |
| `Ship_ResistanceAmadeo` | Ship и численные параметры формы, скоростей и пропульсивного коэффициента | Эмпирическая оценка сопротивления, коэффициентов и мощности. Назначение и переменные сверять с `resistanceAmadeo/Amadeo.py`; модель не содержит взаимодействия двух поплавков |
| `Ship_ResistanceBlountFox` | Ширина, водоизмещение, килеватость, продольный ЦТ, скорости и КПД | Оценка сопротивления с поправкой Blount–Fox к глиссирующей модели Savitsky; отдельный вариант сравнения с Savitsky |
| `Ship_ResistanceHoltrop` | Водоизмещение, LWL/B/T, коэффициенты формы, нос, транец, выступающие части, скорость и КПД | Разложение сопротивления и мощность. Метод для соответствующих обычных водоизмещающих форм; общий Cb катамарана нельзя подставлять как коэффициент однокорпусника |
| `Ship_ResistanceSavitsky` | Ширина, масса, килеватость, продольный ЦТ, скорости, шаг дифферента и КПД | Глиссирующая модель: сопротивление, дифферент, подъёмная сила и мощность. Применимость к океанскому катамарану ECONA пока не установлена |
| `Ship_SeakeepingSetMesh` — назначение сетки | Выбрать Mesh и Ship | Привязывает **готовую** сетку к Ship; сама команда сетку не строит. При нескольких выбранных Mesh используется первая, поэтому объединять оба поплавка заранее |
| `Ship_SeakeepingRAOs` — амплитудно-частотные характеристики | LoadCondition, назначенная панельная сетка, диапазон периодов | Через Capytaine решает радиацию и дифракцию и строит RAO для шести степеней свободы и 36 направлений волн. Требует дополнительной проверки системы координат и матриц |

**«Контурный чертёж» / Ship Outline.** Ссылка на русской странице является
красной ссылкой; в текущем Ship этой команды нет. Смысл инструмента изучен по
первому уроку: поперечные сечения, батоксы и ватерлинии в трёх проекциях.
Реализовывать через `Shape.slice()` / Part Cross-sections и TechDraw.
Начальная сетка из 21 поперечного сечения — учебный пример; для наших острых
оконечностей нужны дополнительные сечения и проверка чувствительности к шагу.

## Система координат и готовность модели

Ship ожидает X вдоль судна к носу, Y к левому борту, Z вверх, начало —
пересечение миделя между перпендикулярами с основной плоскостью. Все длины CAD
внутренне хранятся в миллиметрах; расчётные функции используют `Units.Quantity`,
а Capytaine — метры.

В `ECONA_ECONA.FCStd` X начинается у кормы, Y уже симметричен относительно
центра судна, Z оставлен из исходной модели и **не является ватерлинией**.
Нельзя считать длину габарита 13,6 м автоматически длиной Lpp или LWL.
Перед расчётом создавать отдельную расчётную копию с преобразованием
`Xcalc = Xmodel − Xmid`, `Zcalc = Zmodel − Zbaseline`; сохранять прямое и обратное
преобразования, положение перпендикуляров и источник проектной ватерлинии.
Нижняя точка шверта не задаёт основную плоскость поплавков.

Проверка текущего файла: 137 объектов; PortSkin и StarboardSkin — валидные,
но **незамкнутые Shell**, по 19 447 граней и 58,0066 м². Solid отсутствуют.
Толщины, материалы, действительная масса, ЦТ, инерция и проектная осадка
не заданы. Полная запись — `calculations/ship/model-readiness.json`.

Сейчас допустимы сечения и геометрические измерения. Для судовой гидростатики
нужно подготовить два замкнутых объёма внешних обводов, проверить ориентацию,
герметичность, отсутствие самопересечений и положительный объём. Крышки
расчётного объёма должны отвечать выбранной непроницаемой границе;
их создание не означает назначения палубе материала или толщины.
Для аварийной остойчивости понадобится другая постановка с затопляемыми
отсеками: обычная неповреждённая GZ это не моделирует.

**Обновление 10.10.2026:** из этих обшивок построены отдельные замкнутые
расчётные Solid — [модель и паспорт](24_closed_calculation_hulls.md).
Основная компоновка осталась с открытыми обшивками; расчётные крышки добавлены
только в отдельном файле. Они условные: вертикальные срезы должны оставаться
ниже Zcalc=0,926 м; при крене и дифференте нужна проверка их погружения.

## Нагрузка, единицы и проверка результатов

Для обшивки задавать поверхностную плотность из выбранной технологии:
слои, сердцевина, смола и покрытия. Для набора — фактические сечения и
материалы либо проверенные погонные массы. Сетки старых деталей сами по себе
не доказывают наличие объёма материала или заданной толщины.
Аккумуляторы, моторы, солнечные панели, лебёдки, кайт и снабжение учитывать
реальными массами с координатами; людей — в нескольких возможных положениях.
Не подменять массу судна его водоизмещением при произвольной осадке.

В LoadCondition список весов начинается в A6, танков — C6;
D6 и ниже — плотность жидкости **кг/м³**, E6 и ниже — уровень **0…1 по высоте**.
Новые танки в состоянии нагрузки пусты; стандартная плотность жидкости 998
кг/м³ — не плотность морской воды. Для неквадратного танка заполнение 0,5 по
высоте обычно не означает половину объёма.

Плотность забортной воды в Hydrostatics и GZ по умолчанию 1025 кг/м³;
переменные заданы **в двух разных модулях**. При пресной воде менять обе и
сохранять значение в паспорте расчёта. Локальная поправка RAO передаёт такую
же плотность и g в Capytaine.

Таблица Hydrostatics: A — Δ в тоннах, B — T в метрах, C — смоченная площадь
в м², D — MCT в т·м на 1 см, E — ватерлиния в м², F — XCB в метрах,
G — KB, H — BMt, I/J/K — Cb/Cf/Cm. Заголовок F в исходном коде `KBl [m]`
вводит в заблуждение: туда записывается **XCB**, не метацентрическая величина.
MCT вычисляется с приближением GML ≈ BML; это не переносится на поперечный GM.
Коэффициенты по общему bounding box катамарана включают промежуток между
поплавками; отличать их от коэффициентов каждого поплавка.

Строевая в исходном коде принудительно получает нулевую площадь на обоих
концах. При погружённом транце проверять предельное сечение отдельно;
интеграл такой строевой нельзя считать эталоном объёма без этой поправки.

Проверять `GMt = KB + BMt − KG`, `BMt = Iwp,x / V`, `BMl = Iwp,y / V`,
`Δ = ρV`. Моменты инерции ватерлинии имеют размерность **м⁴**, массы — кг·м².
Для каждого положения контролировать остаток баланса массы
`abs(ρV − m) / m` и моментов. Штатный GZ ограничен 20 итерациями,
его допуск по осадке нормирован на максимальное водоизмещение корпуса и
может быть слишком грубым. Перед предметным расчётом определить и проверить
требуемую точность, повторить с ужесточением допусков и шага крена.

Кайт требует отдельного внешнего момента от вектора тяги и плеча точки
крепления относительно ЦТ. Затем этот момент сопоставлять с `mg·GZ`.
Одна диаграмма GZ не рассчитывает автоматику кайта, динамический порыв,
заливание, удар моста волной или восстановление после переворота.
Учебные критерии IMO из старого урока не переносить на ECONA автоматически:
применимую методику выбирать после назначения, категории и регистрации судна.

## Сопротивление и электрическая мощность

Все четыре команды установлены и их численные модули/диалоги импортируются.
Их формулы не валидированы для текущих обводов ECONA. В них нет параметра
разноса поплавков и модели их волнового взаимодействия. Сумма сопротивлений
двух изолированных поплавков может служить отдельной оценкой, но не заменяет
расчёт всего катамарана.

По габаритной длине 13,6 м скорость 7–10 узлов даёт ориентировочный Fn
0,312–0,445; это лишь диапазон для планирования, поскольку реальная LWL
ещё не установлена. Крейсерскую скорость с кайтом и экономичную скорость
только на моторах рассчитывать раздельно.

У Amadeo/Holtrop численные функции получают длины в метрах, объёмы в м³,
скорости в м/с; сопротивление возвращается в кН, мощности в кВт.
Savitsky/Blount–Fox получают скорости в **узлах**, водоизмещение в **тоннах**,
длины в метрах, углы в градусах; исходные массивы сопротивления и мощности
имеют Н и Вт, графический экспорт делит их на 1000. В GUI поля этих методов
разбираются через `.Value`, поэтому подписанные единицы в строке могут дать
масштаб внутренних единиц FreeCAD. Для воспроизводимости предпочтителен
вызов численной функции с явно подготовленными единицами и проверкой выходов.
Не доверять автоматическим LCG и килеватости: исходный диалог выводит их из
центра величины и B/T, что не задаёт действительный ЦТ и угол днища.

Оценка полезной мощности `Pe = R·v`; требуемая электрическая мощность включает
КПД винта, взаимодействия с корпусом, передачи, мотора и контроллера.
Propulsive coefficient из эмпирической команды не является автоматически
КПД всей системы BLDC–винт. Capytaine RAO не рассчитывает вязкое сопротивление
или расход энергии на движение. Для взаимодействия поплавков дальше нужен
проверенный специальный метод, испытания либо отдельная CFD-постановка.
CFD не является зависимостью Ship; установка OpenFOAM описана отдельно в
[реестре программ](11_software.md).

В [странице Savitsky](https://wiki.freecad.org/Ship_ResistanceSavitsky) указаны
границы: `1 ≤ CV ≤ 13`, где `CV = v / sqrt(gB)`; `2° ≤ τ ≤ 15°`;
динамическое отношение длины к ширине `λ ≤ 4`. Для
[поправки Blount–Fox](https://wiki.freecad.org/Ship_ResistanceBlountFox):
`FΔ ≥ 1`, где `FΔ = v / sqrt(g·V^(1/3))`, и `LCG / LP ≤ 0,46`.
Смысл LCG и проекционной длины киля LP сверять с исходным методом, а не
подставлять координату ЦТ относительно миделя. Диалог может использоваться
без Ship при ручном вводе данных. Проверки в коде не заменяют всех границ
метода; конечность и физический смысл результатов контролировать отдельно.

## Качка и панельная модель

Назначать сетку обоих поплавков без внутренних переборок и лишних стенок.
Проверять нормали, вырожденные панели, соответствие геометрии ватерлинии
и сходимость по размеру панели и диапазону частот. При пересечении поверхности
воды Capytaine обрезает сетку; размеры передаются в метрах.

GUI запрашивает периоды в секундах; в API `ω = 2π/T` в рад/с.
Порядок степеней свободы — Surge, Sway, Heave, Roll, Pitch, Yaw.
Сохранить подписи координат и матриц, а не только голые массивы.
Обе матрицы должны быть 6×6, причём матрица масс, жёсткости и определения
вращательных степеней свободы обязаны относиться к **одной точке и системе**.
Официальная [документация Capytaine](https://capytaine.org/stable/user_manual/hydrostatics.html)
явно различает `center_of_mass` и `rotation_center`.

Оставшиеся ограничения обвязки Ship: начало вращений по умолчанию (0,0,0),
не задаётся явно преобразованный ЦТ; инерция жидкости танков не включается
в `weights_inertia`. Проверенный здесь пример имеет ЦТ на начале вращений
после вычитания осадки и пустые танки. **Его успешный запуск не подтверждает
корректность RAO произвольной компоновки.** Для ECONA перед RAO проверить
общую систему отсчёта, все связи матриц и вклад танков; при необходимости
использовать прямую постановку Capytaine с явно заданным ЦТ и центром вращений.

Текущая команда формирует задачи при нулевой поступательной скорости.
Это линейная частотная модель малых движений; её нельзя объявлять расчётом
ходовой качки при 7–10 узлах. Вязкое демпфирование, слеминг и динамика кайта
нуждаются в отдельных моделях. См. [обработку результатов Capytaine](https://capytaine.org/stable/user_manual/post_pro.html).

## Установка, исправления и доказательства

Исходный [Ship](https://github.com/FreeCAD/freecad.ship) зафиксирован на commit
`8ddc63c726779d339680ad9e42cee2be0bd2e1a9` (metadata 2024.11.26).
[Plot](https://github.com/FreeCAD/Plot) — ветка v2024.11.26, commit
`c98ff0a58fbb9071ce0fd9f2534c68b647d7d1c7`.
Каталоги: `~/.local/share/FreeCAD/Mod/Ship` и `Mod/Plot`.
Capytaine и зависимости: `~/.local/share/FreeCAD/v1-1/AdditionalPythonPackages/py311`.
Новый процесс FreeCADCmd подтвердил автоматическое обнаружение всех модулей.

Wheel-пакеты этих дополнительных зависимостей сохранены в
`software/wheels/freecad-py311`, контрольные суммы —
`software/freecad-ship-wheels.json`. Для восстановления в **том же комплектном
Python 3.11** после проверки манифеста можно выполнить из корня проекта:

```bash
environment/.local/opt/freecad/squashfs-root/AppRun python -m pip install --no-index --no-deps --find-links software/wheels/freecad-py311 --target environment/.local/share/FreeCAD/v1-1/AdditionalPythonPackages/py311 -r software/freecad-ship-requirements.txt
```

Команда предназначена для восстановления отсутствующих пакетов; обновление
FreeCAD/Python требует нового согласования бинарной совместимости.

В исходном Ship обнаружены и локально исправлены:

1. `Part.Face` от раздельных контуров поплавков создавал невалидную единую
   грань. Использован FaceMakerBullseye с поддержкой раздельных граней и дыр.
2. Compound не имеет `MatrixOfInertia`: моменты площади отдельных граней
   объединены по теореме переноса осей относительно общего центра площади;
   исправлены потребители BM и RAO.
3. Устаревший вызов погружения сетки заменён API Capytaine 3;
   масса задаётся скаляром, инерция — размеченной матрицей 6×6 вместо 3×3.
4. Плотность и ускорение в задачах BEM согласованы с гидростатикой.

Патч — `software/ship-multihull.patch`, описание —
`software/ship-multihull-patch.json`. Он **локальный**, не опубликован upstream.
Обновление аддона может его потерять. `tools/ship/apply_compatibility_patch.py`
повторяемо применяет патч только к проверенной версии и отказывается править
другой commit. После обновлений требуются повторные проверки.

| Проверка | Результат |
|---|---|
| Два прямоугольных поплавка 10×1×2 м, осадка 1 м, разнос центров 5 м | V=20 м³, Δ=20 500 кг при ρ=1025 кг/м³ |
| Ватерлиния | 2 валидные грани, 20 м²; Ixx=126,666667 м⁴, Iyy=166,666667 м⁴ — совпадение с аналитикой |
| Метацентрические радиусы | BMt=6,333333 м, BMl=8,333333 м — совпадение с аналитикой |
| Вложенные контуры | Прямоугольное кольцо: площадь 12 м² и Ixx=20 м⁴ — совпадение с аналитикой |
| Танк 2 м³ | 50% высоты → 1 м³; полный → 2 м³ |
| Нагрузка 20 500 кг, KG=1 м | Равновесие T=1 м, GZ(0)=0; GZ при 1° согласуется с GM·sinφ |
| Посадка | Создана визуализация равновесия в отдельном проверочном документе |
| RAO | Выполнены 6 задач радиации и 1 дифракции при ω=1 рад/с на 112 панелях; конечные комплексные ответы для 6 степеней свободы |
| Plot | График создан и сохранён штатным модулем FreeCAD |
| FEM/Gmsh | На отдельном кубе 1 м построена сетка: 131 узел, 364 объёмных элемента |
| CalculiX | Путь сохранён в FEM, версия 2.23 распознана штатным `FemToolsCcx` |
| Команды и новый запуск | 16 команд Ship зарегистрированы; 17 пакетов/диалогов импортированы; модули найдены в новом процессе |

Результаты: `software/ship-verification.json`, `ship-fem-verification.json`,
`ship-command-imports.json`, `ship-startup-verification.json`.
Версии и SHA-256: `software/ship-installation.json`, `ship-python-versions.json`.
Не путать комплектный Gmsh 4.15.0 для FEM с ранее установленным проектным
Gmsh Python 4.15.2. Проверка сетки не является расчётом прочности судна.
Проверочный RAO подтверждает выполнение цепочки, но не точность физического
результата: сходимость этой грубой сетки не исследовалась.

## Порядок следующих расчётов

1. Проверить неизменность основной модели; создать отдельный расчётный
   документ и замкнутые внешние объёмы обоих поплавков. Назначить основную
   плоскость, перпендикуляры и рабочую ватерлинию. Сохранить преобразование.
2. Ship CreateShip → строевая → таблицы гидростатики в диапазоне осадок.
   Сверить объёмы, центры и инерцию ватерлинии независимым расчётом.
3. Составить весовую ведомость и состояния: порожнее судно; 4 и 8 человек;
   полные и частично заполненные танки; минимальные запасы; неблагоприятное
   перемещение людей и оборудования. Незаполненные входы в
   `calculations/ship/econa-inputs.yaml` означают неизвестные данные.
4. Рассчитать посадку и GZ для каждого состояния; отдельно приложить моменты
   кайта и проверить устойчивость сходимости и выбранную методику оценки.
5. Обосновать метод сопротивления именно двух поплавков; связать R(v) с
   тяговой характеристикой кайта, винтом, BLDC и энергетическим балансом.
6. Составить проверенные матрицы качки и сетку Capytaine; пройти проверки
   точки вращения, ЦТ, жидкостей, скорости и панельной сходимости.
7. Для прочности перенести расчётные нагрузки в FEM, назначить физическую
   конструкцию, материалы и соединения, выполнить сходимость сетки.

Будущие расчёты сохранять с входными данными, единицами, SHA-256 геометрии,
версией инструмента/патча, остатками равновесия и границами применимости.
Это правило записано также в корневом `AGENTS.md` проекта.

## Повторение проверок и офлайн-поиск

В консоли **работающего GUI FreeCAD**:

```python
p = 'project/tools/ship/verify_ship_gui.py'
exec(compile(open(p).read(), p, 'exec'), {'__file__': p, '__name__': '__main__'})
p = 'project/tools/ship/verify_fem_gui.py'
exec(compile(open(p).read(), p, 'exec'), {'__file__': p, '__name__': '__main__'})
```

В терминале из корня проекта:

```bash
environment/.local/opt/freecad/squashfs-root/AppRun freecadcmd tools/ship/probe_startup.py
.venv/bin/python tools/ship/apply_compatibility_patch.py
python3 tools/search.py 'Ship'
tools/start-library
```

Исходники аддонов сохранены в `library/software/ship-workbench/*.upstream.tar.gz`
с лицензиями и комплектными примерами. Русская/английская wiki и оба урока
сохранены как HTML и поисковый TXT; дополнительно сохранён официальный архив
Markdown, README и ключевые страницы Capytaine. Происхождение, время получения
и контрольные суммы — `research/ship_workbench_sources.json`. Все тексты
добавлены в общий офлайн-поиск проекта. Страницы источников и их указания
считаются справочным материалом; они не заменяют требования пользователя.
Поисковые копии Python-кода установленного Ship находятся в подпапке `code`;
их происхождение, SHA-256 и признак локального исправления —
`research/ship_code_sources.json`.