-update docs

- fix python example

Author: EmilDohne

PhotoshopAPI/src/Core/Geometry/BezierSurface.h

@@ -15,7 +15,8 @@ PSAPI_NAMESPACE_BEGIN
 namespace Geometry
 {
 
-    /// A generic Bezier surface struct with 
+    /// A generic implementation of a cubic bezier surface. In the context of the PhotoshopAPI we use this to evaluate 
+    /// warps stored as cubic bezier surfaces. This struct is specialized for use within Photoshop.
     struct BezierSurface 
     {
 

PhotoshopAPI/src/LayeredFile/LayerTypes/Layer.h

@@ -107,7 +107,16 @@ struct Layer : public MaskMixin<T>
 	/// 
 	/// In photoshop this is stored as a `uint8_t` from 0-255 but access and write is 
 	/// in terms of a float for better consistency.
-	void opacity(float value) noexcept { m_Opacity = static_cast<uint8_t>(value * 255.0f); }
+	void opacity(float value) noexcept 
+	{
+		if (value < 0.0f || value > 1.0f)
+		{
+			PSAPI_LOG_WARNING("Layer", "Encountered opacity value not between 0-1. Clamping this to fit into that range");
+		}
+		value = std::clamp<float>(value, 0.0f, 1.0f);
+
+		m_Opacity = static_cast<uint8_t>(value * 255.0f); 
+	}
 
 	/// The layers' width from 0 - 300,000
 	virtual uint32_t width() const noexcept { return m_Width; }

PhotoshopAPI/src/LayeredFile/LayeredFile.h

@@ -77,15 +77,12 @@ struct LayeredFile
 	ICCProfile icc_profile() const noexcept { return m_ICCProfile; }
 	void icc_profile(ICCProfile profile) noexcept { m_ICCProfile = std::move(profile); }
 
-	/// \defgroup dpi The files' dots per inch (dpi) resolution
-	/// @{
+	/// The files' dots per inch (dpi) resolution
 	float& dpi() noexcept { return m_DotsPerInch; }
 	float dpi() const noexcept { return m_DotsPerInch; }
 	void dpi(float resolution) { m_DotsPerInch = resolution; }
-	/// @} 
 
-	/// \defgroup width The files' width from 1 - 300,000
-	/// @{
+	/// The files' width from 1 - 300,000
 	uint64_t& width() noexcept { return m_Width; }
 	uint64_t width() const noexcept { return m_Width; }
 	void width(uint64_t file_width)
@@ -100,10 +97,8 @@ struct LayeredFile
 		}
 		m_Width = file_width;
 	}
-	/// @} 
 
-	/// \defgroup height The files' height from 1 - 300,000
-	/// @{
+	/// The files' height from 1 - 300,000
 	uint64_t& height() noexcept { return m_Height; }
 	uint64_t height() const noexcept { return m_Height; }
 	void height(uint64_t file_height)
@@ -118,7 +113,6 @@ struct LayeredFile
 		}
 		m_Height = file_height;
 	}
-	/// @} 
 
 	/// Retrieve the bounding box describing the canvas, will always have a minimum of 0, 0
 	Geometry::BoundingBox<double> bbox() const noexcept 
@@ -128,38 +122,27 @@ struct LayeredFile
 			Geometry::Point2D<double>(static_cast<double>(width()), static_cast<double>(height())));
 	}
 
-	/// \defgroup colormode The files' colormode
+	/// \brief The files' colormode
 	/// 
 	/// Currently we only fully support RGB, CMYK and Greyscale.
-	/// 
-	/// @{
 	Enum::ColorMode& colormode() noexcept { return m_ColorMode; }
 	Enum::ColorMode colormode() const noexcept { return m_ColorMode; }
 	void colormode(Enum::ColorMode color_mode) noexcept { m_ColorMode = color_mode; }
-	/// @} 
 
-	/// \defgroup bitdepth The files' bitdepth
+	/// \brief The files' bitdepth
 	/// 
 	/// As this is managed by the template type T we do not actually allow users
 	/// to set this.
-	/// 
-	/// @{
 	Enum::BitDepth bitdepth() const noexcept { return m_BitDepth; }
-	/// @} 
 
-	/// \defgroup linked_layer 
-	/// 
-	/// Primarily for internal user or advanced users. Users should usually not have to 
+	/// Primarily for internal use or advanced users. Users should usually not have to 
 	/// touch this as it's handled for them by SmartObjects themselves
 	/// 
 	/// LinkedLayers describe a global state of linked files. Their purpose is to store
 	/// the raw image data of smart objects such that any layer can have different resolution
 	/// than the smart object and for deduplication.
-	/// 
-	/// @{
 	std::shared_ptr<LinkedLayers<T>> linked_layers() noexcept { return m_LinkedLayers; }
 	const std::shared_ptr<LinkedLayers<T>> linked_layers() const noexcept { return m_LinkedLayers; }
-	/// @} 
 
 
 	LayeredFile() = default;

PhotoshopAPI/src/LayeredFile/LinkedData/LinkedLayerData.h

@@ -29,7 +29,10 @@ PSAPI_NAMESPACE_BEGIN
 
 enum class LinkedLayerType
 {
+	/// Links the data internlly, meaning the raw file bytes will be stored in-file
 	data,
+	/// Links the data externally, meaning only the transformed image is stored in-file 
+	/// with the original data residing on disk
 	external
 };
 

PhotoshopExamples/AddLayerMasks/add_layer_masks.py

@@ -18,7 +18,7 @@ def main() -> None:
     img_data[0] = 255
     mask = np.full((height, width), 128, np.uint8)
 
-    img_layer = psapi.ImageLayer_8bit(img_data, "Layer Red", layer_mask=mask)
+    img_layer = psapi.ImageLayer_8bit(img_data, "Layer Red", layer_mask=mask, width=width, height=height)
 
     # Add the layer and write to disk
     document.add_layer(img_layer)

PhotoshopExamples/CreateSimpleDocument/create_simple_document.py

@@ -20,7 +20,7 @@ def main() -> None:
 
     # Similar to the C++ version we can adjust parameters of the layer after it has been added to the document
     # as long as it happens before we write to disk
-    img_layer.opacity = 128
+    img_layer.opacity = .5
 
     document.write(os.path.join(os.path.dirname(__file__), "WriteSimpleFile.psd"))
 

PhotoshopExamples/CreateSimpleDocument/main.cpp

@@ -35,7 +35,7 @@ int main()
 
 	// It is perfectly legal to modify a layers properties even after it was added to the document as attributes
 	// are only finalized on export
-	layer->opacity(128u);
+	layer->opacity(.5);
 
 	// Convert to PhotoshopFile and write to disk. Note that from this point onwards 
 	// our LayeredFile instance is no longer usable

README.md

@@ -45,33 +45,31 @@ Features
 =========
 
 Supported:
-- Read and write of \*.psd and \*.psb files
-- Creating and modifying simple and complex nested layer structures
-- Pixel Masks
-- Modifying layer attributes (name, blend mode, image data etc.)
-- Setting the Display ICC Profile
-- Setting the DPI of the document
-- 8-, 16- and 32-bit files
-- RGB, CMYK and Grayscale color modes
-- All compression modes known to Photoshop
+	- Read and write of \*.psd and \*.psb files
+	- Creating and modifying simple and complex nested layer structures
+	- Smart Objects (replacing, warping, extracting)
+	- Pixel Masks
+	- Modifying layer attributes (name, blend mode etc.)
+	- Setting the Display ICC Profile
+	- 8-, 16- and 32-bit files
+	- RGB, CMYK and Grayscale color modes
+	- All compression modes known to Photoshop
 
 Planned:
-- Support for Adjustment Layers (planned `v0.6.0`)
-- Support for Vector Masks
-- Support for Text Layers
-- Support for Smart Object Layers (planned `v0.6.0`)
-- Indexed and Duotone Color Modes
+	- Support for Adjustment Layers
+	- Support for Vector Masks
+	- Support for Text Layers
+	- Indexed, Duotone Color Modes
 
 Not Supported:
-- Files written by the PhotoshopAPI do not contain a valid merged image in order to save size meaning they will not behave properly when opened in
-    third party apps requiring these (such as Lightroom)
-- Lab and Multichannel Color Modes 
-
+	- Files written by the PhotoshopAPI do not contain a valid merged image in order to save size meaning they will not behave properly when opened in
+	  third party apps requiring these (such as Lightroom)
+	- Lab and Multichannel Color Modes 
 
 Python
 ==============
 
-The PhotoshopAPI comes with fully fledged Python bindings which can be simply installed using
+The PhotoshopAPI comes with Python bindings which can be installed using
 ```
 $ py -m pip install PhotoshopAPI
 ```
@@ -134,77 +132,65 @@ Below is a minimal example to get started with opening a PhotoshopFile, removing
 ### C++ 
 
 ```cpp	
-using namespace PhotoshopAPI;
-
-// Initialize an 8-bit layeredFile. This must match the bit depth of the PhotoshopFile.
-// To initialize this programmatically please refer to the ExtendedSignature example
-LayeredFile<bpp8_t> layeredFile = LayeredFile<bpp8_t>::read("InputFile.psd");
-
-// Do some operation, in this case delete
-layeredFile.removeLayer("SomeGroup/SomeNestedLayer");	
-
-// One could write out to .psb instead if wanted and the PhotoshopAPI will take 
-// care of any conversion internally
-LayeredFile<bpp8_t>::write(std::move(layeredFile), "OutputFile.psd");
+using namespace NAMESPACE_PSAPI;
+
+// Initialize some constants that we will need throughout the program
+const static uint32_t width = 64u;
+const static uint32_t height = 64u;
+
+// Create an 8-bit LayeredFile as our starting point, 8- 16- and 32-bit are fully supported
+LayeredFile<bpp8_t> document = { Enum::ColorMode::RGB, width, height };
+// Create our individual channels to add to our image layer. Keep in mind that all these 3 channels need to 
+// be specified for RGB mode
+std::unordered_map <Enum::ChannelID, std::vector<bpp8_t>> channelMap;
+channelMap[Enum::ChannelID::Red] = std::vector<bpp8_t>(width * height, 255u);
+channelMap[Enum::ChannelID::Green] = std::vector<bpp8_t>(width * height, 0u);
+channelMap[Enum::ChannelID::Blue] = std::vector<bpp8_t>(width * height, 0u);
+
+ImageLayer<bpp8_t>::Params layerParams = {};
+layerParams.name = "Layer Red";
+layerParams.width = width;
+layerParams.height = height;
+
+auto layer = std::make_shared<ImageLayer<bpp8_t>>(std::move(channelMap), layerParams);
+document.add_layer(layer);
+
+// It is perfectly legal to modify a layers properties even after it was added to the document as attributes
+// are only finalized on export
+layer->opacity(.5f);
+
+// Convert to PhotoshopFile and write to disk. Note that from this point onwards 
+// our LayeredFile instance is no longer usable
+LayeredFile<bpp8_t>::write(std::move(document), "WriteSimpleFile.psd");
 ```
 
 
-The same code for reading and writing can also be used to for example `LayeredFile::moveLayer` or `LayeredFile::addLayer` as well as extracting any image data
+The same code for reading and writing can also be used to for example `LayeredFile::move_layer_` or `LayeredFile::add_layer` as well as extracting any image data
 
 ### Python
 
 ```py
+import os
+import numpy as np
 import psapi
 
-# Read the layered_file using the LayeredFile helper class, this returns a 
-# psapi.LayeredFile_*bit object with the appropriate bit-depth
-layered_file = psapi.LayeredFile.read("InputFile.psd")
-
-# Do some operation, in this case delete
-layered_file.remove_layer()
+# Initialize some constants that we will need throughout the program
+width = 64
+height = 64
+color_mode = psapi.enum.ColorMode.rgb
 
-# Write back out to disk
-layered_file.write("OutFile.psd")
-```
+# Generate our LayeredFile instance
+document = psapi.LayeredFile_8bit(color_mode, width, height)
 
-We can also do much more advanced things such as taking image data from one file and transferring 
-it to another file, this can be across file sizes, psd/psb and even bit-depth!
-
-```py
-import psapi
-import numpy as np
-import os
+img_data = np.zeros((3, height, width), np.uint8)
+img_data[0] = 255
+# When creating an image layer the width and height parameter are required if its not a zero sized layer
+img_layer = psapi.ImageLayer_8bit(img_data, "Layer Red", width=width, height=height)
+document.add_layer(img_layer)
 
+# Similar to the C++ version we can adjust parameters of the layer after it has been added to the document
+# as long as it happens before we write to disk
+img_layer.opacity = .5
 
-def main() -> None:
-    # Read both our files, they can be open at the same time or we can also read one file,
-    # extract the layer and return just that layer if we want to save on RAM.
-    file_src = psapi.LayeredFile.read("GraftSource_16.psb")
-    file_dest = psapi.LayeredFile.read("GraftDestination_8.psd")
-
-    # Extract the image data and convert to 8-bit.
-    lr_src: psapi.ImageLayer_16bit = file_src["GraftSource"]
-    img_data_src = lr_src.get_image_data()
-    img_data_8bit = {}
-    for key, value in img_data_src.items():
-        value = value / 256 # Convert from 0-65535 -> 0-255
-        img_data_8bit[key] = value.astype(np.uint8)
-
-    # Reconstruct an 8bit converted layer
-    img_layer_8bit = psapi.ImageLayer_8bit(
-        img_data_8bit, 
-        layer_name=lr_src.name, 
-        width=lr_src.width, 
-        height=lr_src.height, 
-        blend_mode=lr_src.blend_mode, 
-        opacity=lr_src.opacity
-        )
-
-    # add the layer and write out to file!
-    file_dest.add_layer(img_layer_8bit)
-    file_dest.write("GraftDestination_8_Edited.psd")
-
-
-if __name__ == "__main__":
-    main()
-```
+document.write(os.path.join(os.path.dirname(__file__), "WriteSimpleFile.psd"))
+```

docs/doxygen/code/layeredfile.rst

@@ -9,8 +9,8 @@ around internally also very efficient
 Usage
 -----
 
-The code snippets below show some examples of how one would generally use a LayeredFile. For more detailed examples please visit the PhotoshopExamples/ directory
-on the github page
+The code snippets below show some examples of how one would generally use a LayeredFile. 
+For more detailed examples please visit :ref:`examples`
 
 .. tab:: Read and Modify
 
@@ -22,10 +22,10 @@ on the github page
 		LayeredFile<bpp16_t> layeredFile = LayeredFile<bpp16_t>::read("InFile.psd");
 
 		// Move a layer one level up in the hierarchy
-		layeredFile.moveLayer("Group/NestedGroup/Image", "Group");
+		layeredFile.move_layer("Group/NestedGroup/Image", "Group");
 
 		// Delete the now empty group from the document
-		layeredFile.removeLayer("Group/NestedGroup");
+		layeredFile.remove_layer("Group/NestedGroup");
 
 		// We can now convert the LayeredFile to a PhotoshopFile and write it out (this is done internally
 		// but can be exposed, see the ExtendedSignature example for more information)
@@ -57,7 +57,7 @@ on the github page
 		layerParams.height = height;
 
 		auto layer = std::make_shared<ImageLayer<bpp8_t>>(std::move(channelMap), layerParams);
-		document.addLayer(layer);
+		document.add_layer(layer);
 
 		LayeredFile<bpp8_t>::write(std::move(layeredFile), "OutFile.psd");
 
@@ -66,7 +66,7 @@ on the github page
 Layer Type Derivatives
 ----------------------
 
-Below you can find a list of layers that one is able to add to the LayeredFile instance. Keep in mind that some of these are not fully implemented yet
+Below you can find a list of layers that one is able to add to the LayeredFile instance.
 
 .. toctree::
    :maxdepth: 2
@@ -78,6 +78,12 @@ Below you can find a list of layers that one is able to add to the LayeredFile i
    layers/sectiondivider.rst
    layers/smartobject.rst
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Global Data:
+
+   util/linked_layer_data.rst
+
 
 
 Conversion Functions
@@ -107,6 +113,7 @@ LayeredFile Struct
 
 .. doxygenstruct:: LayeredFile
 	:members:
+	:undoc-members:
 
 |
 

docs/doxygen/code/layers/baselayer.rst

@@ -11,8 +11,7 @@ Base Layer Type
 
 This is the base definition for all layer types which holds generic data such as name, mask data, opacity etc.
 This class is not supposed to be used directly but instead through any of its subclassed layers as this layer type
-doesn't exist in Photoshop itself. There is a further specialization `_ImageDataLayerType<T>` which acts as a generic 
-interface for ImageData types such as `SmartObjectLayer<T>` and `ImageLayer<T>`
+doesn't exist in Photoshop itself.
 
 .. _layer:
 .. doxygenstruct:: Layer