GafferML : Add TensorToImage

This allows tensors to be converted back to GafferImage images, after they have been processed by the Inference node.

include/GafferML/TensorToImage.h

@@ -0,0 +1,91 @@
+//////////////////////////////////////////////////////////////////////////
+//
+//  Copyright (c) 2024, Cinesite VFX Ltd. All rights reserved.
+//
+//  Redistribution and use in source and binary forms, with or without
+//  modification, are permitted provided that the following conditions are
+//  met:
+//
+//      * Redistributions of source code must retain the above
+//        copyright notice, this list of conditions and the following
+//        disclaimer.
+//
+//      * Redistributions in binary form must reproduce the above
+//        copyright notice, this list of conditions and the following
+//        disclaimer in the documentation and/or other materials provided with
+//        the distribution.
+//
+//      * Neither the name of John Haddon nor the names of
+//        any other contributors to this software may be used to endorse or
+//        promote products derived from this software without specific prior
+//        written permission.
+//
+//  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+//  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+//  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+//  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+//  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+//  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+//  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+//  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+//  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+//  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+//  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+//
+//////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+#include "GafferML/Export.h"
+#include "GafferML/TensorPlug.h"
+
+#include "GafferImage/FlatImageSource.h"
+
+namespace GafferML
+{
+
+class GAFFERML_API TensorToImage : public GafferImage::FlatImageSource
+{
+
+	public :
+
+		explicit TensorToImage( const std::string &name=defaultName<TensorToImage>() );
+		~TensorToImage() override;
+
+		GAFFER_NODE_DECLARE_TYPE( GafferML::TensorToImage, TensorToImageTypeId, GafferImage::FlatImageSource );
+
+		TensorPlug *tensorPlug();
+		const TensorPlug *tensorPlug() const;
+
+		Gaffer::StringVectorDataPlug *channelsPlug();
+		const Gaffer::StringVectorDataPlug *channelsPlug() const;
+
+		Gaffer::BoolPlug *interleavedChannelsPlug();
+		const Gaffer::BoolPlug *interleavedChannelsPlug() const;
+
+		void affects( const Gaffer::Plug *input, AffectedPlugsContainer &outputs ) const override;
+
+	protected :
+
+		void hashMetadata( const GafferImage::ImagePlug *parent, const Gaffer::Context *context, IECore::MurmurHash &h ) const override;
+		IECore::ConstCompoundDataPtr computeMetadata( const Gaffer::Context *context, const GafferImage::ImagePlug *parent ) const override;
+
+		void hashFormat( const GafferImage::ImagePlug *parent, const Gaffer::Context *context, IECore::MurmurHash &h ) const override;
+		GafferImage::Format computeFormat( const Gaffer::Context *context, const GafferImage::ImagePlug *parent ) const override;
+
+		void hashDataWindow( const GafferImage::ImagePlug *parent, const Gaffer::Context *context, IECore::MurmurHash &h ) const override;
+		Imath::Box2i computeDataWindow( const Gaffer::Context *context, const GafferImage::ImagePlug *parent ) const override;
+
+		void hashChannelNames( const GafferImage::ImagePlug *parent, const Gaffer::Context *context, IECore::MurmurHash &h ) const override;
+		IECore::ConstStringVectorDataPtr computeChannelNames( const Gaffer::Context *context, const GafferImage::ImagePlug *parent ) const override;
+
+		void hashChannelData( const GafferImage::ImagePlug *parent, const Gaffer::Context *context, IECore::MurmurHash &h ) const override;
+		IECore::ConstFloatVectorDataPtr computeChannelData( const std::string &channelName, const Imath::V2i &tileOrigin, const Gaffer::Context *context, const GafferImage::ImagePlug *parent ) const override;
+
+		static size_t g_firstPlugIndex;
+
+};
+
+IE_CORE_DECLAREPTR( TensorToImage )
+
+} // namespace GafferML

python/GafferMLTest/TensorToImageTest.py

@@ -0,0 +1,130 @@
+##########################################################################
+#
+#  Copyright (c) 2024, Cinesite VFX Ltd. All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are
+#  met:
+#
+#      * Redistributions of source code must retain the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer in the documentation and/or other materials provided with
+#        the distribution.
+#
+#      * Neither the name of John Haddon nor the names of
+#        any other contributors to this software may be used to endorse or
+#        promote products derived from this software without specific prior
+#        written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+#  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+#  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+#  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+#  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+#  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+#  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+#  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+#  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+#  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+#  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+##########################################################################
+
+import unittest
+
+import imath
+
+import IECore
+
+import Gaffer
+import GafferTest
+import GafferImage
+import GafferImageTest
+import GafferML
+
+class TensorToImageTest( GafferImageTest.ImageTestCase ) :
+
+	def testNoInput( self ) :
+
+		node = GafferML.TensorToImage()
+		with self.assertRaisesRegex( Gaffer.ProcessException, "Empty tensor" ) :
+			node["out"].dataWindow()
+
+	def testNonMatchingChannels( self ) :
+
+		tensor = GafferML.Tensor(
+			IECore.Color3fVectorData( [ imath.Color3f( 1, 2, 3 ) ] ),
+			[ 1, 1, 3 ]
+		)
+
+		tensorToImage = GafferML.TensorToImage()
+		tensorToImage["tensor"].setValue( tensor )
+		tensorToImage["interleavedChannels"].setValue( True )
+		self.assertEqual( tensorToImage["out"].dataWindow(), imath.Box2i( imath.V2i( 0 ), imath.V2i( 1 ) ) )
+
+		# Only two channels specified.
+
+		tensorToImage["channels"].setValue( IECore.StringVectorData( [ "R", "G" ] ) )
+		self.assertEqual( tensorToImage["out"].channelNames(), IECore.StringVectorData( [ "R", "G" ] ) )
+		self.assertEqual( tensorToImage["out"].channelData( "R", imath.V2i( 0 ) )[0], 1 )
+		self.assertEqual( tensorToImage["out"].channelData( "G", imath.V2i( 0 ) )[0], 2 )
+
+		with self.assertRaisesRegex( RuntimeError, 'Invalid channel "B"' ) :
+			tensorToImage["out"].channelData( "B", imath.V2i( 0 ) )
+
+		# Duplicate channels specified. We just take the first.
+
+		tensorToImage["channels"].setValue( IECore.StringVectorData( [ "R", "R", "B" ] ) )
+		self.assertEqual( tensorToImage["out"].channelNames(), IECore.StringVectorData( [ "R", "B" ] ) )
+		self.assertEqual( tensorToImage["out"].channelData( "R", imath.V2i( 0 ) )[0], 1 )
+		self.assertEqual( tensorToImage["out"].channelData( "B", imath.V2i( 0 ) )[0], 3 )
+
+		with self.assertRaisesRegex( RuntimeError, 'Invalid channel "G' ) :
+			tensorToImage["out"].channelData( "G", imath.V2i( 0 ) )
+
+		# Too many channels specified. We error if the extra channel is accessed.
+
+		tensorToImage["channels"].setValue( IECore.StringVectorData( [ "R", "G", "B", "A" ] ) )
+		self.assertEqual( tensorToImage["out"].channelNames(), IECore.StringVectorData( [ "R", "G", "B", "A" ] ) )
+		self.assertEqual( tensorToImage["out"].channelData( "R", imath.V2i( 0 ) )[0], 1 )
+		self.assertEqual( tensorToImage["out"].channelData( "G", imath.V2i( 0 ) )[0], 2 )
+		self.assertEqual( tensorToImage["out"].channelData( "B", imath.V2i( 0 ) )[0], 3 )
+
+		with self.assertRaisesRegex( RuntimeError, 'Channel "A" out of range' ) :
+			tensorToImage["out"].channelData( "A", imath.V2i( 0 ) )
+
+		# Channels skipped by entering empty strings.
+
+		tensorToImage["channels"].setValue( IECore.StringVectorData( [ "R", "", "B" ] ) )
+		self.assertEqual( tensorToImage["out"].channelNames(), IECore.StringVectorData( [ "R", "B" ] ) )
+		self.assertEqual( tensorToImage["out"].channelData( "R", imath.V2i( 0 ) )[0], 1 )
+		self.assertEqual( tensorToImage["out"].channelData( "B", imath.V2i( 0 ) )[0], 3 )
+
+		with self.assertRaisesRegex( RuntimeError, 'Invalid channel "G' ) :
+			tensorToImage["out"].channelData( "G", imath.V2i( 0 ) )
+
+	def testRoundTripWithImageToTensor( self ) :
+
+		image = GafferImage.Checkerboard()
+
+		imageToTensor = GafferML.ImageToTensor()
+		imageToTensor["image"].setInput( image["out"] )
+		imageToTensor["channels"].setInput( image["out"]["channelNames"])
+
+		tensorToImage = GafferML.TensorToImage()
+		tensorToImage["tensor"].setInput( imageToTensor["tensor"] )
+		tensorToImage["channels"].setInput( image["out"]["channelNames"])
+
+		self.assertImagesEqual( tensorToImage["out"], image["out"] )
+
+		imageToTensor["interleaveChannels"].setValue( True )
+		tensorToImage["interleavedChannels"].setValue( True )
+
+		self.assertImagesEqual( tensorToImage["out"], image["out"] )
+
+if __name__ == "__main__":
+	unittest.main()

python/GafferMLTest/__init__.py

@@ -39,6 +39,7 @@
 from .DataToTensorTest import DataToTensorTest
 from .InferenceTest import InferenceTest
 from .ImageToTensorTest import ImageToTensorTest
+from .TensorToImageTest import TensorToImageTest
 
 if __name__ == "__main__":
 	import unittest

python/GafferMLUI/TensorToImageUI.py

@@ -0,0 +1,95 @@
+##########################################################################
+#
+#  Copyright (c) 2024, Cinesite VFX Ltd. All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are
+#  met:
+#
+#      * Redistributions of source code must retain the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer in the documentation and/or other materials provided with
+#        the distribution.
+#
+#      * Neither the name of John Haddon nor the names of
+#        any other contributors to this software may be used to endorse or
+#        promote products derived from this software without specific prior
+#        written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+#  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+#  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+#  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+#  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+#  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+#  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+#  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+#  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+#  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+#  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+##########################################################################
+
+import Gaffer
+import GafferML
+
+Gaffer.Metadata.registerNode(
+
+	GafferML.TensorToImage,
+
+	plugs = {
+
+		"tensor" : [
+
+			"description",
+			"""
+			The input tensor to be turned into an image. Typically this would be connected
+			to the output of an Inference node that is doing image processing.
+			""",
+
+			"plugValueWidget:type", "",
+			"nodule:type", "GafferUI::StandardNodule",
+
+		],
+
+		"channels" : [
+
+			"description",
+			"""
+			The names to give to the channels in the output image. These
+			channels are unpacked from the tensor in the order in which they are
+			specified. For example, an order of `[ "B", "G", "R" ]` might be
+			needed for use with models trained on images using OpenCV
+			conventions. An empty channel name may be used to skip a channel
+			when unpacking.
+			""",
+
+		],
+
+		"interleavedChannels" : [
+
+			"description",
+			"""
+			Indicates that the channels are interleaved in the input tensor, in
+			which case they will be deinterleaved when converting to the output
+			image. Whether or not channels are interleaved will depend on the
+			model from which the tensor is obtained.
+			""",
+
+		],
+
+		"out" : [
+
+			"description",
+			"""
+			The output image.
+			""",
+
+		],
+
+	}
+)

python/GafferMLUI/__init__.py

@@ -37,5 +37,6 @@
 from . import DataToTensorUI
 from . import InferenceUI
 from . import ImageToTensorUI
+from . import TensorToImageUI
 
 __import__( "IECore" ).loadConfig( "GAFFER_STARTUP_PATHS", subdirectory = "GafferMLUI" )