Unit Images

Returns if two RGB colors are be considered equal, i.e. each component in Color1 is different than corresponding component in Color2 by Tolerance or less.

True if ImageClass is one of the items ImageClasses array or inherits from (i.e. is descendant of) one of them.

This is a shortcut for InImageClasses(Image.ClassType, ImageClasses)

True if both arrays contain exactly the same classes in the same order.

May be extended in the future to do better checks and return true also if both array contain the same classes but in different order, and one array may contain the same classes duplicated any times. So the intention is that you should treat both arrays as sets (i.e. order of elements is ignored).

The problem is that this function should be lighting fast (as the main purpose of it is to use it in constructions like setting property values, e.g. if ImageClassesArraysEqual(Value, SomeProperty) then begin SomeProperty := Value; ... do some lengthy operations to update new value of SomeProperty ... end; ), and doing smarter checks may cost us a little time.

So for now this function returns - true if for sure both arrays contain the same classes and - false if *possibly* they don't contain the same classes.

Encode RGB color as Greg Ward's Red + Green + Blue + Exponent format, thus allowing you to encode 12 bytes (3 * SizeOf(Single) = 3 * 4 = 12) in 4 bytes (4 * SizeOf(Byte) = 4), usually without any significant loss.

Each component of V (red, green, blue) is from range [0, +infinity), not merely from [0, 1]. I.e. V must have only nonnegative values.

Decode Red + Green + Blue + Exponent back into RGB 3 x Single.

jesli RoundToByteRGB to zwroci result.Kind = ikRGB (patrz komentarze przy LoadRGBEToByteRGB). Wpp. result.Kind = ikRGBE.

Img.Kind musi byc in ikRGB, ikRGBE (checked even in RELEASE). W tym pierwszym przypadku - patrz komentarze przy SaveRGBEFromByteRGB.

rownowazne ImageRecToRGB(LoadRGBE(Stream, true)). Nazwa jest taka pokrecona ("ToByteRGB") bo naprawde rzadko powinienes tego uzywac i zawsze musisz zdawac sobie sprawe z ograniczen : zaokraglanie do bajtu w zasadzie zabija caly sens formatu RGBE. Odczytaj plik RGBE to RGB (3xByte) i potem go zapisz (chocby nawet z powrotem w RGBE) a stracisz cala precyzje zawarta w formacie RGBE.

rownowazne SaveRGBE(ImageRecFromRGB(Img), Stream). Podobnie jak przy ImageRGBToRGBE, konwersja RGB na RGBE jest bezstratna ale moze byc bezsensowna (po co ci precyzja skoro dane juz sa pozbawione precyzji ?)

Only 256-color PCX can be handled. This will not probably be ever improved (al least by me, Kambi), since I don't use PCX images anymore. Use PNG if you want lossless compression.

Loads only the first image in .ppm file.

——————————————————————————

SaveXxx. Each file format has specialized SaveXxx that allows you to give some parameters special for given format.

Each format must also have procedure with two parameters (const Img: TRGBImage; Stream: TStream), this will be used with ImageFormatsInfo[]. This means that below we must use overloading instead of default parameters, since pointers to given procedures must be compatible with TRGBImageSaveFunc.

interlaced = false

quality = 90

LoadAnyPNG : zaladuj png. Jesli frAny to zwroci ikRGB lub ikAlpha, w zaleznosci od tego co jest zapisane w obrazku. Jesli frWithoutAlpha to zwroci ikRGB - jesli obrazek mial zapisane alpha to albo je usunie (jesli ConvertToRequired = true) lub rzuci wyjatek EUnableToLoadImage (jesli ConvertToRequired = false). Podobnie jesli frWithAlpha to zwroci obrazek ikAlpha - jesli obrazek nie mial zapisanego alpha to doda alpha (jesli ConvertToRequired = true) rowne wszedzie 1.0 (czyli High(Byte)) lub rzuci wyjatek EUnableToLoadImage (jesli ConvertToRequired = false).

LoadPNG mozna teraz zrealizowac jako proste ImageRecToRGB(LoadAnyPNG(Stream, frWithoutAlpha, true));

SaveAnyPNG: Img moze miec Kind = ikRGB (wtedy zadziala jak SavePNG) lub ikAlpha (wtedy zapamieta alpha obrazka w pliku)

znajdz TImageFormat ktore ma podane dane fileext. fileext moze byc z poczatkowa kropka (a wiec tak jak zwraca je ExtractFileExt) lub bez. Zwraca false i nie zmienia ImgFormat jesli nie ma formatu o danym fileext.

jak wyzej, ale jesli nie ma formatu o danym fileext to zwraca DefFormat.

jak FileExtToImageFormat ale tutaj interesuje nas tylko czy MOZESZ taki TImageFormat znalezc, a nie : jaki on jest.

j.w. z OnlyLoadable = true, OnlySaveable = false.

zadana jest nazwa pliku s, bez koncowego rozszerzenia (takze bez koncowej kropki przed rozszerzeniem). Probuje doklejac rozszerzenia sposrod ImageFormatInfos[].exts az znajdzie takie ze po doklejeniu plik istnieje (NormalFileExists).

Jesli nie znajdzie - wersja Try zwroci '', wersja bez Try rzuci wyjatek ENoExistingImageExt. Jesli znajdzie - zwraca nazwe pliku z doklejonym rozszerzeniem. Jesli OnlyLoadable, bedzie szukal tylko wsrod formatow loadable.

te funkcje moga byc czasem wygodne do konstruowania zapytan w rodzaju SaveFileAs, przyklad - patrz glViewImage i RaytraceToWindow. ListImageExtsLong wypisuje rozszerzenia kazdego formatu w osobnej linii, wypisuje tez FormatName. Linie sa rozdzielane przez nl, jak zwykle ostatnia linia NIE jest zakonczona nl. Kazda linia zaczyna sie od LinePrefix, potem od razu jakies nie-biale znaki np. 'ppm - PPM, Portable Pixel Map' ListImageExtsShort wypisuje wszystkie dozwolone rozszerzenia oddzielone ', ' (przecinek + spacja).

Jesli resizeTo[] <> 0 to dany wymiar bedzie resizowany.

ImageProc, jesli <> nil, jest wywolywane dla zaladowanego image'a PRZED wykonaniem ewentualnego skalowania. Ma to zastosowanie np. gdy chcesz zaladowac stosunkowo maly obrazek z pliku, zamienic go np. na czarno-bialy i potem przeskalowac na bardzo duzy rozmiar. W takiej sytuacji duzo bardziej ekonomiczne jest wywolanie konwersji na black&white jeszcze PRZED skalowaniem, a wiec najlepiej przekaz MakeBlackAndWhite jako ImageProc. Acha, jesli chcesz to mozesz w ImageProc zmienic rozmiary obrazka. (chociaz dla typowego resizu pewnie wygodniej bedzie uzyc parametrow resizeToX, resizeToY)

SaveImage ktore pobiera jako parametr TImage. W zaleznosci od klasy Img :

TRGBImage - wybiera odpowiednie SaveXxx na podstawie Format, TypeExt lub FileName (jezeli podales FileName to juz nie podajesz Stream, naturalnie). Jesli rozszerzenie nie odpowiada niczemu co umiemy zapisywac - sejwuje do formatu DefaultSaveImageFormat.

TRGBEImage - jezeli image format (zapisany implicite w FileName lub TypeExt) = ifRGBE to zapisze obrazek uzywajac SaveRGBE(Img, fname), a wiec precyzja zawarta w wewnetrznym formacie ikRGBE bedzie zapisana w formacie pliku ifRGBE.

Jezeli image format <> ifRGBE to skonwertuje obrazek do RGB (uzywajac TRGBEImage.ToRGBImage) i zapisze uzywajac SaveImage(TRGBImage,..). Wiec precyzja zawarta w wewnetrznym formacie ikRGBE nie bedzie zapisana w pliku, bo formaty inne niz ifRGBE nie pozwalaja na to.

TODO: zrobic jakas ladniejsza forme, uwzgledniajaca fakt ze byc moze kiedys zrobie jeszcze jakis format pliku (if) / lub obrazka w pamieci (ik) ktore uznawalbym za precyzyjne na poziomie float.

TAlphaImage: Format must support saving alpha images then (for now this means only ifPNG), zapisze wtedy obrazek z alpha. Wpp. rzuci wyjatek Exception. TODO: do it nicer, z podobnymi parametrami jak przy LoadImage.

ImageAlphaConst : - najpierw, jezeli obrazek jest pozbawiony alpha to je dodaj. - potem ustaw wszedzie alpha = alphaConst

Na podstawie filename zgaduje format pliku ktory mozemy zapisac do takiego filename (czyli robi FileExtToImageFormatDef( ExtractFileExt(ImageFilename), false, true, DefaultSaveImageFormat)) (wersja z ImgFormat juz ma to w ImgFormat).

Potem wybiera TImageKind ktory ma najwiekszy sens dla zadanego formatu - tzn. taki TImageKind ze przy sejwowaniu obrazka o takim Kind do pliku o takiej nazwie (a wiec i takim formacie) nie bedzie robiona zadna strata, nie bedzie zadnego odrzucania kanalu alpha ani precyzji i zakresu floatow. W tym momencie oznacza to ze dla ifRGBE zwroci ikRGBE a dla wszystkich pozostalych ikRGB. W tej chwili zadne format nie ma dac kind z alpha - bede tu musial kiedys dodac jakis arg aby pozwolic tej funkcji na zwracanie kanalu alpha np. dla png.

TImageClass and arrays of TImageClasses —————————–

Note: Don't name it TDynImageClassesArray, as such naming convention is reserved for TDynArray_Base descendants.

Values

• frWithoutAlpha:
• frWithAlpha:
• frAny:

File formats managing —————————————————–

Values

• ifBMP:
• ifPNG:
• ifJPEG:
• ifPCX:
• ifPPM:
• ifIPL:
• ifRGBE:
• ifGIF:
• ifTGA:

As you can see, each file format must have at least one (default) file extension.

LoadImage is the ultimate procedure to load image from file.

Two simple example use cases: Image := LoadImage('filename.png', [], []); (when you don't care what TImage descendant you get) or ImageRGB := LoadImage('filename.png', [TRGBImage], []) as TRGBImage; (when you insist to get TRGBImage, not e.g. TAlphaImage in case png image in file has some alpha channel).

AllowedImageClasses says what image classes are allowed. As a special case, AllowedImageClasses = [] is equivalent to AllowedImageClasses = [TImage] which says that all TImage descendants are allowed. Then this function will do everything it can to load any image into the best subclass of TImage losing as little image information it can.

Example: consider you're loading a PNG file. Let's suppose you're loading it with AllowedImageClasses = []. Then if PNG file will have alpha channel, LoadImage will return TAlphaImage descendant. Else LoadImage will return TRGBImage descendant. Now let's suppose you specified AllowedImageClasses = [TRGBImage]. If PNG file will not have alpha channel, LoadImage will return TRGBImage descendant, as before. But if PNG fill *will* have alpha channel then 1. if ForbiddenConvs does not contain [ilcAlphaDelete], LoadImage will simply ignore alpha channel and return you TRGBImage 2. if ForbiddenConvs does contain [ilcAlphaDelete], LoadImage will exit with exception EUnableToLoadImage. This is somewhat safer, since you can't accidentaly ignore alpha channel that was present in file.

All images have somehow specified RGB colors. Some of them may have alpha channel, some of them may have float precision (for now, this is only for RGBE images). This means that we may have to drop (ignore) these two things while loading image. So you can firbid ignoring them by adding to ForbiddenConvs ilcAlphaDelete and/or ilcFloatPrecDelete values.

There can also happen reverse situation: you e.g. insist that AllowedImageClasses = [TAlphaImage] but given PNG image does not have alpha channel. In this case LoadImage may add "dummy" alpha channel (everywhere equal to 1.0 or High(Byte)). Similar thing when you e.g. gave AllowedImageClasses = [TRGBEImage] but you're loading from PNG image. In this case you want float precision, but image file cannot offer it. So LoadImage can simply convert discreet values to appropriating floating point values. This is usually harmless, but sometimes it may be unwanted, since you're getting something in different format than was in file. So you can add to ForbiddenConvs ilcAlphaAdd and/or ilcFloatPrecAdd to prevent that.

If at any point LoadImage will find that it's unable to satisfy AllowedImageClasses without doing any forbidden convertions in ForbiddenConvs, it will raise EUnableToLoadImage.

Again some example: specify AllowedImageClasses = [TAlphaImage] and ForbiddenConvs = [ilcAlphaAdd] to be sure that LoadImage will return TAlphaImage with alpha channel loaded from file. If file wlil not have alpha channel, EUnableToLoadImage will be raised.

Pl: Jedna nie-1-znaczna dotad sytuacja : jezeli mamy obrazek RGB (tzn. bez alpha, bez precyzji float) a musimy dodac alpha _lub_ precyzje (to znaczy AllowedImageKinds = [ikAlpha, ikRGBE]) i mozemy dodac obie (tzn. nie ma ilcAlphaAdd ani ilcFloatPrecAdd w ForbiddenConvs) to dodamy alpha. (tak czy siak, kombinacja [ikAlpha, ikRGBE] jest malo sensowna, w kazdym realnym zastosowaniu jesli umiesz obsluzyc i ikAlpha i ikRGBE to chyba ikRGB tez umiesz; — jesli kiedys skorzystam z tej zaleznosci to skresle ta linie i dodam tutaj komentarz gdzie to sie moze przydac ——)

Values

• ilcAlphaDelete:
• ilcFloatPrecDelete:
• ilcAlphaAdd:
• ilcFloatPrecAdd:
• ilcRGBFlattenToGrayscale:

= nil if can't load it with alpha channel