FlowPlotPy 0.9.6__tar.gz → 0.9.7__tar.gz

{flowplotpy-0.9.6 → flowplotpy-0.9.7}/FlowPlot_Mega.hpp

@@ -13462,25 +13462,76 @@ namespace FlowPlot
 		float lineGap = 0.0f;
 	};
 
+	/**
+	 * @brief Interface used by FlowPlot to register, measure, and lay out fonts.
+	 *
+	 * FlowPlot resolves text sizes while compiling a template and stores the resulting
+	 * glyph positions in its render commands. Applications that need their own text
+	 * backend can supply an implementation with PlotBuilder::useTextEngine.
+	 *
+	 * When FLOW_PLOT_RENDERER is enabled, FlowPlot provides StbTextEngine and creates a
+	 * temporary instance automatically when no engine was supplied. It registers the
+	 * template's fonts before rendering. Supply an engine when font state must be shared,
+	 * cached, or implemented by another rendering backend.
+	 */
 	class ITextEngine
 	{
 	public:
 		virtual ~ITextEngine() = default;
+
+		/**
+		 * @brief Register a TrueType font face under a FlowPlot font family.
+		 *
+		 * FlowPlot calls this for every entry in a template's @c fonts array. Implementations
+		 * should retain enough font data to serve later measurement and layout requests.
+		 * @param familyName Family name used by templates, for example "Default".
+		 * @param ttfPath Path to a .ttf file.
+		 * @param weight Numeric font weight, normally 400 for regular or 700 for bold.
+		 * @param style Font style for this face.
+		 */
 		virtual void registerFont(
 			std::string_view familyName,
 			const std::filesystem::path& ttfPath,
 			std::uint16_t weight = 400,
 			FontStyle style = FontStyle::Normal) = 0;
+
+		/**
+		 * @brief Return whether a registered face exists for the requested font attributes.
+		 *
+		 * This query lets callers inspect an engine before a template is compiled. The exact
+		 * fallback policy is implementation-defined; StbTextEngine falls back to its
+		 * @c Default regular face when an exact match is unavailable.
+		 */
 		virtual bool hasFont(
 			std::string_view familyName,
 			std::uint16_t weight = 400,
 			FontStyle style = FontStyle::Normal) const = 0;
+
+		/**
+		 * @brief Measure text without producing glyph positions.
+		 *
+		 * FlowPlot uses these metrics when resolving automatically sized text boxes. Return
+		 * dimensions in the same pixel coordinate system used by @ref layoutText.
+		 */
 		virtual TextMeasurement measureText(
 			std::string_view familyName,
 			std::uint16_t weight,
 			FontStyle style,
 			float fontSizePx,
 			std::string_view text) const = 0;
+
+		/**
+		 * @brief Lay out text and return glyph placements for rendering.
+		 *
+		 * Each placement is relative to the text origin. FlowPlot consumes the returned
+		 * metrics and placements directly when it constructs a TextCommand.
+		 * @param familyName Font family requested by the template.
+		 * @param weight Numeric font weight requested by the template.
+		 * @param style Font style requested by the template.
+		 * @param fontSizePx Font size in pixels.
+		 * @param text UTF-8 text to lay out.
+		 * @param maxWidth Maximum layout width in pixels, or infinity for unbounded text.
+		 */
 		virtual LaidOutText layoutText(
 			std::string_view familyName,
 			std::uint16_t weight,
@@ -13556,11 +13607,47 @@ namespace FlowPlot
 		std::vector<RenderCommand> commands{};
 	};
 
-	inline FontStyle parseFontStyle(std::string_view rawStyle);
-	inline const char* fontStyleName(FontStyle style) noexcept;
-
 } // namespace FlowPlot
 
+namespace FlowInternal
+{
+	inline FlowPlot::FontStyle parseFontStyle(std::string_view rawStyle)
+	{
+		std::string style;
+		style.reserve(rawStyle.size());
+		for (const char c : rawStyle)
+		{
+			if (c >= 'A' && c <= 'Z')
+				style.push_back(static_cast<char>(c - 'A' + 'a'));
+			else
+				style.push_back(c);
+		}
+
+		if (style.empty() || style == "normal")
+			return FlowPlot::FontStyle::Normal;
+		if (style == "italic")
+			return FlowPlot::FontStyle::Italic;
+		if (style == "oblique")
+			return FlowPlot::FontStyle::Oblique;
+
+		throw std::invalid_argument("parseFontStyle: unsupported font style '" + std::string(rawStyle) + "'");
+	}
+
+	inline const char* fontStyleName(FlowPlot::FontStyle style) noexcept
+	{
+		switch (style)
+		{
+		case FlowPlot::FontStyle::Italic:
+			return "italic";
+		case FlowPlot::FontStyle::Oblique:
+			return "oblique";
+		case FlowPlot::FontStyle::Normal:
+		default:
+			return "normal";
+		}
+	}
+} // namespace FlowInternal
+
 // ===== BEGIN inlined FlowPlot_Internal.hpp =====
 
 #include <cctype>
@@ -15084,7 +15171,7 @@ namespace FlowInternal
 				textEngine,
 				textSpec.fontFamily,
 				textSpec.fontWeight,
-				FlowPlot::parseFontStyle(textSpec.fontStyle),
+				FlowInternal::parseFontStyle(textSpec.fontStyle),
 				textSpec.fontSize,
 				textSpec.text,
 				path);
@@ -15124,7 +15211,7 @@ namespace FlowInternal
 			resolved.fontFamily = titleSpec.fontFamily;
 			resolved.fontSize = titleSpec.fontSize;
 			resolved.fontWeight = titleSpec.fontWeight;
-			resolved.fontStyle = FlowPlot::parseFontStyle(titleSpec.fontStyle);
+			resolved.fontStyle = FlowInternal::parseFontStyle(titleSpec.fontStyle);
 			resolved.color = parseColor(titleSpec.color, "figure.title.color");
 			resolved.hAlign = parseHorizontalAlign(titleSpec.hAlign, "figure.title.hAlign");
 			resolved.vAlign = parseVerticalAlign(titleSpec.vAlign, "figure.title.vAlign");
@@ -15160,7 +15247,7 @@ namespace FlowInternal
 					textEngine,
 					elementSpec.fontFamily,
 					elementSpec.fontWeight,
-					FlowPlot::parseFontStyle(elementSpec.fontStyle),
+					FlowInternal::parseFontStyle(elementSpec.fontStyle),
 					elementSpec.fontSize,
 					elementSpec.text,
 					path + ".box");
@@ -15184,7 +15271,7 @@ namespace FlowInternal
 			cache.label.fontFamily = elementSpec.fontFamily;
 			cache.label.fontSize = elementSpec.fontSize;
 			cache.label.fontWeight = elementSpec.fontWeight;
-			cache.label.fontStyle = FlowPlot::parseFontStyle(elementSpec.fontStyle);
+			cache.label.fontStyle = FlowInternal::parseFontStyle(elementSpec.fontStyle);
 			cache.label.color = parseColor(elementSpec.color, path + ".color");
 			cache.label.clipToBox = elementSpec.clip;
 			cache.label.box.w = textWidth;
@@ -15358,7 +15445,7 @@ namespace FlowInternal
 			resolved.fontFamily = titleSpec.fontFamily;
 			resolved.fontSize = titleSpec.fontSize;
 			resolved.fontWeight = titleSpec.fontWeight;
-			resolved.fontStyle = FlowPlot::parseFontStyle(titleSpec.fontStyle);
+			resolved.fontStyle = FlowInternal::parseFontStyle(titleSpec.fontStyle);
 			resolved.color = parseColor(titleSpec.color, path + ".color");
 			resolved.hAlign = parseHorizontalAlign(titleSpec.hAlign, path + ".hAlign");
 			resolved.vAlign = parseVerticalAlign(titleSpec.vAlign, path + ".vAlign");
@@ -16316,7 +16403,7 @@ namespace FlowInternal
 						textEngine,
 						axisSpec.tickLabelFontFamily,
 						axisSpec.tickLabelFontWeight,
-						FlowPlot::parseFontStyle(axisSpec.tickLabelFontStyle),
+						FlowInternal::parseFontStyle(axisSpec.tickLabelFontStyle),
 						axisSpec.tickLabelFontSize,
 						tickText,
 						path + ".tickLabels[" + std::to_string(majorIdx) + "]");
@@ -16358,7 +16445,7 @@ namespace FlowInternal
 							textEngine,
 							titleSpec.fontFamily,
 							titleSpec.fontWeight,
-							FlowPlot::parseFontStyle(titleSpec.fontStyle),
+							FlowInternal::parseFontStyle(titleSpec.fontStyle),
 							titleSpec.fontSize,
 							titleSpec.text,
 							path + ".title.box");
@@ -16601,7 +16688,7 @@ namespace FlowInternal
 					textEngine,
 					axisSpec.tickLabelFontFamily,
 					axisSpec.tickLabelFontWeight,
-					FlowPlot::parseFontStyle(axisSpec.tickLabelFontStyle),
+					FlowInternal::parseFontStyle(axisSpec.tickLabelFontStyle),
 					axisSpec.tickLabelFontSize,
 					tickText,
 					path + ".tickLabels[" + std::to_string(majorIdx) + "]");
@@ -16617,7 +16704,7 @@ namespace FlowInternal
 				label.fontFamily = axisSpec.tickLabelFontFamily;
 				label.fontSize = axisSpec.tickLabelFontSize;
 				label.fontWeight = axisSpec.tickLabelFontWeight;
-				label.fontStyle = FlowPlot::parseFontStyle(axisSpec.tickLabelFontStyle);
+				label.fontStyle = FlowInternal::parseFontStyle(axisSpec.tickLabelFontStyle);
 				label.color = tickLabelColor;
 				label.hAlign = FlowPlot::HorizontalAlign::Left;
 				label.vAlign = FlowPlot::VerticalAlign::Top;
@@ -16657,7 +16744,7 @@ namespace FlowInternal
 						textEngine,
 						titleSpec.fontFamily,
 						titleSpec.fontWeight,
-						FlowPlot::parseFontStyle(titleSpec.fontStyle),
+						FlowInternal::parseFontStyle(titleSpec.fontStyle),
 						titleSpec.fontSize,
 						titleSpec.text,
 						path + ".title.box");
@@ -16688,7 +16775,7 @@ namespace FlowInternal
 				title.fontFamily = titleSpec.fontFamily;
 				title.fontSize = titleSpec.fontSize;
 				title.fontWeight = titleSpec.fontWeight;
-				title.fontStyle = FlowPlot::parseFontStyle(titleSpec.fontStyle);
+				title.fontStyle = FlowInternal::parseFontStyle(titleSpec.fontStyle);
 				title.color = parseColor(titleSpec.color, path + ".title.color");
 				title.hAlign = parseHorizontalAlign(titleSpec.hAlign, path + ".title.hAlign");
 				title.vAlign = parseVerticalAlign(titleSpec.vAlign, path + ".title.vAlign");
@@ -18359,42 +18446,23 @@ namespace FlowInternal
 
 namespace FlowPlot
 {
-	inline FontStyle parseFontStyle(std::string_view rawStyle)
-	{
-		std::string style;
-		style.reserve(rawStyle.size());
-		for (const char c : rawStyle)
-		{
-			if (c >= 'A' && c <= 'Z')
-				style.push_back(static_cast<char>(c - 'A' + 'a'));
-			else
-				style.push_back(c);
-		}
-
-		if (style.empty() || style == "normal")
-			return FontStyle::Normal;
-		if (style == "italic")
-			return FontStyle::Italic;
-		if (style == "oblique")
-			return FontStyle::Oblique;
-
-		throw std::invalid_argument("parseFontStyle: unsupported font style '" + std::string(rawStyle) + "'");
-	}
-
-	inline const char* fontStyleName(FontStyle style) noexcept
-	{
-		switch (style)
-		{
-		case FontStyle::Italic:
-			return "italic";
-		case FontStyle::Oblique:
-			return "oblique";
-		case FontStyle::Normal:
-		default:
-			return "normal";
-		}
-	}
-
+	/**
+	 * @brief Register every font listed in a parsed FlowPlot template.
+	 *
+	 * Reads the optional top-level @c fonts array and registers each face with
+	 * @p textEngine. This is useful when an application manages an ITextEngine itself
+	 * rather than using the renderer-provided default.
+	 *
+	 * @code{.cpp}
+	 * FlowPlot::StbTextEngine fonts;
+	 * rapidjson::Document templateJson;
+	 * templateJson.Parse(R"({"fonts":[]})");
+	 * FlowPlot::registerFonts(fonts, templateJson);
+	 * @endcode
+	 * @param textEngine Text engine that will receive the registered font faces.
+	 * @param templateJson Parsed template JSON object containing an optional fonts array.
+	 * @throws std::runtime_error if the fonts array is malformed.
+	 */
 	inline void registerFonts(ITextEngine& textEngine, const rapidjson::Value& templateJson)
 	{
 		if (!templateJson.IsObject())
@@ -18441,10 +18509,17 @@ namespace FlowPlot
 				family,
 				std::filesystem::path(fontPath),
 				static_cast<std::uint16_t>(rawWeight),
-				parseFontStyle(style));
+				FlowInternal::parseFontStyle(style));
 		}
 	}
 
+	/**
+	 * @brief Parse a template JSON string and register every font listed in it.
+	 *
+	 * This overload parses @p templateJsonText and then behaves exactly like the
+	 * RapidJSON-value overload. Use it when the template has not already been parsed.
+	 * @throws std::runtime_error if the JSON cannot be parsed or the fonts array is malformed.
+	 */
 	inline void registerFonts(ITextEngine& textEngine, std::string_view templateJsonText)
 	{
 		rapidjson::Document templateJson;
@@ -18468,6 +18543,23 @@ namespace FlowPlot
 		friend PlotBuilder makePlot(const std::filesystem::path& path);
 		friend PlotBuilder& plot(const std::filesystem::path& path);
 
+		/**
+		 * @brief Set one template property to a scalar value.
+		 *
+		 * Property paths use dotted JSON paths and optional array indexes, for example
+		 * "figure.width" or "panels[0].axes.x.label".
+		 * The value is copied into the builder's template, so string arguments do not need
+		 * to outlive this call.
+		 *
+		 * @code{.cpp}
+		 * auto builder = FlowPlot::makePlot("Scatter")
+		 *     .set("figure.width", 1280)
+		 *     .set("panels[0].title.text", "Quarterly results");
+		 * @endcode
+		 *
+		 * @return This builder, so calls can be chained.
+		 * @throws std::invalid_argument if the property path is empty or invalid.
+		 */
 		PlotBuilder& set(std::string_view property, value valueArg)
 		{
 			if (property.empty())
@@ -18516,6 +18608,21 @@ namespace FlowPlot
 			return setJsonValue(property, std::move(normalizedValue));
 		}
 
+		/**
+		 * @brief Set one template property from a raw JSON value.
+		 *
+		 * Use this for arrays or objects that cannot be represented by FlowPlot::value.
+		 * FlowPlot parses and copies the value into its template; @p jsonText may therefore
+		 * be a temporary string.
+		 *
+		 * @code{.cpp}
+		 * builder.setJsonRaw("panels[0].axes.x.range", "[0.0, 100.0]");
+		 * @endcode
+		 *
+		 * @return This builder, so calls can be chained.
+		 * @throws std::invalid_argument if the property path is empty or invalid.
+		 * @throws std::runtime_error if jsonText is not a valid JSON value.
+		 */
 		PlotBuilder& setJsonRaw(std::string_view property, std::string_view jsonText)
 		{
 			if (property.empty())
@@ -18679,6 +18786,26 @@ namespace FlowPlot
 
 	public:
 
+		/**
+		 * @brief Bind an external contiguous data span to a template dataset field.
+		 *
+		 * datasetField must use the form "dataset.field". The caller owns the data and
+		 * FlowPlot stores only a non-owning view of it.
+		 *
+		 * @warning @p data must remain valid and must not be reallocated until
+		 * getCommands() or writePng() has completed. Destroying, resizing, or moving its
+		 * backing storage first leaves the builder with a dangling view and causes invalid
+		 * plot execution.
+		 *
+		 * @code{.cpp}
+		 * std::vector<double> x{1.0, 2.0, 3.0};
+		 * auto builder = FlowPlot::makePlot("Scatter").withData("series.x", x);
+		 * FlowPlot::RenderPlot commands = builder.getCommands(); // x is still alive
+		 * @endcode
+		 *
+		 * @return This builder, so calls can be chained.
+		 * @throws std::invalid_argument if the field path or element type is unsupported.
+		 */
 		template<typename T>
 		PlotBuilder& withData(std::string_view datasetField, std::span<const T> data)
 		{
@@ -18710,26 +18837,81 @@ namespace FlowPlot
 			return *this;
 		}
 
+		/**
+		 * @brief Bind a std::vector to a template dataset field.
+		 *
+		 * This is a convenience overload for withData(datasetField, std::span<const T>).
+		 * It does not copy the vector's elements.
+		 *
+		 * @warning @p data must outlive getCommands() or writePng(), and it must not be
+		 * resized or otherwise reallocated before that operation completes. The builder
+		 * retains only @c data.data() and its element count.
+		 */
 		template<typename T, typename Allocator>
 		PlotBuilder& withData(std::string_view datasetField, const std::vector<T, Allocator>& data)
 		{
 			return withData<T>(datasetField, std::span<const T>(data.data(), data.size()));
 		}
 
+		/**
+		 * @brief Set the text engine used for font registration, text measurement, and rendering.
+		 *
+		 * The text engine is referenced, not copied, and must outlive calls to getCommands()
+		 * or writePng(). With FLOW_PLOT_RENDERER enabled, omitting this call selects a
+		 * temporary default StbTextEngine and automatically registers template fonts.
+		 * Provide an engine explicitly to reuse registered fonts or use a custom backend.
+		 *
+		 * @warning @p textEngine must remain alive until getCommands() or writePng() has
+		 * completed. The builder stores a non-owning pointer; destroying the engine first
+		 * leaves it dangling and causes invalid plot execution.
+		 *
+		 * @code{.cpp}
+		 * FlowPlot::StbTextEngine fonts{"/path/to/default.ttf"};
+		 * auto builder = FlowPlot::makePlot("Report").useTextEngine(fonts);
+		 * auto commands = builder.getCommands();
+		 * @endcode
+		 *
+		 * @return This builder, so calls can be chained.
+		 */
 		PlotBuilder& useTextEngine(const ITextEngine& textEngine)
 		{
 			textEngine_ = &textEngine;
 			return *this;
 		}
 
+		/**
+		 * @brief Register this template's fonts into the supplied text engine.
+		 *
+		 * This is useful when the application owns the text engine and wants FlowPlot to
+		 * load the template's fonts before rendering. It is not necessary when using the
+		 * default renderer text engine, because that registration happens automatically.
+		 */
 		void registerTemplateFonts(ITextEngine& textEngine) const
 		{
 			registerFonts(textEngine, template_);
 		}
 
+		/**
+		 * @brief Compile the current template and bound data into renderer-independent commands.
+		 *
+		 * This resolves template defaults, data bindings, plot geometry, and text layout.
+		 * Use the returned commands with a custom renderer, or call writePng() when the
+		 * built-in renderer is enabled.
+		 * @return A RenderPlot containing plot dimensions, background, and drawing commands.
+		 * @throws std::runtime_error if the template, data bindings, or text setup are invalid.
+		 */
 		RenderPlot getCommands() const;
 
 #ifdef FLOW_PLOT_RENDERER
+		/**
+		 * @brief Render the current plot directly to a PNG file.
+		 *
+		 * This performs the same compilation as getCommands() and rasterizes the result with
+		 * the built-in renderer. If no text engine was supplied, it uses the temporary
+		 * StbTextEngine described in @ref ITextEngine.
+		 * @param outputPath Destination .png path.
+		 * @throws std::runtime_error if rendering, font setup, or file writing fails.
+		 */
 		void writePng(const std::filesystem::path& outputPath) const;
 #endif
 
@@ -18739,6 +18921,23 @@ namespace FlowPlot
 		const ITextEngine* textEngine_ = nullptr;
 	};
 
+	/**
+	 * @brief Load a JSON template and return an independent PlotBuilder by value.
+	 *
+	 * If path has no .json extension, ".json" is appended. Use this form when you want
+	 * multiple independent builders, need to keep a builder beyond another plot request,
+	 * or wrap FlowPlot from another language. The returned builder owns its template and
+	 * can be moved or stored normally.
+	 *
+	 * @code{.cpp}
+	 * auto left = FlowPlot::makePlot("Scatter");
+	 * auto right = FlowPlot::makePlot("Histogram");
+	 * left.withData("series.x", leftData);
+	 * right.withData("bins.values", rightData);
+	 * @endcode
+	 *
+	 * @throws std::runtime_error if the template file cannot be opened or parsed.
+	 */
 	inline PlotBuilder makePlot(const std::filesystem::path& path)
 	{
 		std::filesystem::path jsonPath = path;
@@ -18773,6 +18972,27 @@ namespace FlowPlot
 		return builder;
 	}
 
+	/**
+	 * @brief Load a JSON template into a thread-local builder and return it by reference.
+	 *
+	 * This supports compact chaining such as FlowPlot::plot("Scatter").withData(...).
+	 * Each call replaces the previous thread-local builder for the current thread. It is
+	 * convenient for one immediate build operation, but references and pointers to a
+	 * previous result become invalid after the next plot() call on that thread.
+	 *
+	 * The builder is thread-local: different threads receive different builders and do not
+	 * overwrite each other. Use makePlot() instead when two builders must coexist on the
+	 * same thread, when a builder must be retained, or when explicit ownership is clearer.
+	 *
+	 * @code{.cpp}
+	 * const auto commands = FlowPlot::plot("Scatter")
+	 *     .withData("series.x", x)
+	 *     .withData("series.y", y)
+	 *     .getCommands();
+	 * @endcode
+	 *
+	 * @throws std::runtime_error if the template file cannot be opened or parsed.
+	 */
 	inline PlotBuilder& plot(const std::filesystem::path& path)
 	{
 		static thread_local PlotBuilder builder;
@@ -18792,6 +19012,21 @@ namespace FlowPlot
 #endif
 
 #ifdef FLOW_PLOT_COMPLETE_JSON
+	/**
+	 * @brief Expand a template JSON string with FlowPlot defaults.
+	 *
+	 * The input is normalized using the same defaulting rules applied during plot
+	 * compilation. This is useful for inspecting the effective template or persisting a
+	 * fully specified template.
+	 *
+	 * @code{.cpp}
+	 * std::string complete = FlowPlot::getCompleteJson(R"({"figure":{"width":800}})");
+	 * @endcode
+	 * @param templateJsonText Template JSON document.
+	 * @param pretty Whether to format the returned JSON with indentation.
+	 * @return A complete JSON template string with defaults filled in.
+	 * @throws std::runtime_error if the input JSON cannot be parsed.
+	 */
 	inline std::string getCompleteJson(std::string_view templateJsonText, bool pretty = true)
 	{
 		rapidjson::Document templateJson;
@@ -26102,7 +26337,7 @@ namespace FlowPlot
 			throw std::runtime_error(
 				"StbTextEngine: no registered font for family '" + std::string(familyName) +
 				"', weight " + std::to_string(weight) +
-				", style '" + fontStyleName(style) +
+				", style '" + FlowInternal::fontStyleName(style) +
 				"', and no registered 'Default' fallback");
 		}
 

{flowplotpy-0.9.6 → flowplotpy-0.9.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: FlowPlotPy
-Version: 0.9.6
+Version: 0.9.7
 Summary: Python bindings for the FlowPlot plotting library
 Author: FlowPlot contributors
 License: MIT License

{flowplotpy-0.9.6 → flowplotpy-0.9.7}/flowplot_py.cpp

@@ -163,7 +163,7 @@ namespace
 		out["font_family"] = command.fontFamily;
 		out["font_size"] = command.fontSize;
 		out["font_weight"] = command.fontWeight;
-		out["font_style"] = FlowPlot::fontStyleName(command.fontStyle);
+		out["font_style"] = FlowInternal::fontStyleName(command.fontStyle);
 		out["h_align"] = horizontalAlignName(command.hAlign);
 		out["v_align"] = verticalAlignName(command.vAlign);
 		out["clip_to_box"] = command.clipToBox;

{flowplotpy-0.9.6 → flowplotpy-0.9.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "FlowPlotPy"
-version = "0.9.6"
+version = "0.9.7"
 description = "Python bindings for the FlowPlot plotting library"
 readme = "README.md"
 requires-python = ">=3.10"