<!DOCTYPE HTML PUBLIC -//W3C//DTD HTML 4.01 Transitional//EN>
<html>
  <head>
    <title>photo</title>
  </head>
  <body>

    <h1>photo</h1>

    <p>Встроенный тип полноцветных изображений Tk.</p>

    <h2><a name=СИНТАКСИС></a>СИНТАКСИС</h2>

    <pre>
      <strong>image create photo</strong> ?<em>имя</em>? ?<em>параметры</em>?
    </pre>

    <h2><a name=ОПИСАНИЕ></a>ОПИСАНИЕ</h2>

    <p>Пиксели изображения типа <strong>photo</strong> могут быть
      любого цвета, а также могут быть прозрачными. При сохранении
      изображений этого типа каждый пиксель кодируется 24 битами; при
      выводе пиксела при необходимости используется приближение
      (dithering). Закодированные данные могут быть представлены в
      виде файла или строки, а также в виде C кода через процедурный
      интерфейс. В настоящее время поддерживаются только форматы GIF и
      PPM/PGM; однако в системе имеется интерфейс, облегчающий
      добавление новых форматов изображений. Области, данные для
      которых не представлены, при выводе изображения оказываются
      прозрачными.</p>

    <h2><a name=СОЗДАНИЕ_ИЗОБРАЖЕНИЙ_ТИПА_PHOTO></a>СОЗДАНИЕ ИЗОБРАЖЕНИЙ ТИПА photo</h2>

    <p>Как и все остальные изображения, изображения типа photo
      создаются командой <a href=image.html#create><strong>image
      create</strong></a>. Команда поддерживает следующие параметры:

    <dl>
      <dt><strong>-channel</strong> <em>идКанала</em></dt>

      <dd>Параметр задает имя канала, открытого для чтения, по
	которому должно поступить изображение типа photo. Формат
	данных в канале должен быть таким, для которого существует
	соответствующая программа чтения данных из файла или
	канала.</dd>

      <dt><strong>-data</strong> <em>строка</em></dt>

      <dd>Задает содержимое изображения в виде строки. Формат данных в
	строке должен быть таким, для которого существует
	соответствующая программа чтения данных из строки. Если заданы
	оба параметра <strong>-data</strong> и
	<strong>-file</strong>, то параметр <strong>-file</strong>
	подавляет значение параметра
	<strong>-data</strong>.</dd>

      <dt><strong>-format</strong> <em>имя-формата</em></dt>

      <dd>Задает имя файла, содержащего описание формата данных,
	указанных параметрами <strong>-data</strong> или
	<strong>-file</strong>.</dd>

      <dt><strong>-file</strong> <em>имя</em></dt>

      <dd>Задает имя файла, содержащего данные для изображения типа
	photo. Формат файла должен быть таким, для которого существует
	соответствующая программа чтения данных из файла или
	канала.</dd>

      <dt><strong>-gamma</strong> <em>значение</em></dt>

      <dd>Указывает на то, что распределение цветов для вывода данного
	изображения в окне должно быть исправлено для нелинейного
	дисплея с помощью показателя экспоненты
	<strong>gamma</strong>. (В большинстве CRT интенсивность
	вывода является показательной функцией введенного значения,
	что обеспечивает качественное приближение;
	<strong>gamma</strong> это показатель экспоненты, его значение
	обычно близко к &quot;2&quot;). Указанное значение должно быть
	положительным. По умолчанию параметр имеет значение
	&quot;1&quot; (коррекция не производится). Значения, большие
	единицы, осветляют изображение, меньшие единицы делают его
	темнее.</dd>

      <dt><strong>-height</strong> <em>число</em></dt>

      <dd>Задает высоту изображения в пикселах. Этот параметр
	оказывается полезным, в первую очередь, в ситуациях, когда
	пользователь строит изображение по частям. Значение ноль
	(принятое по умолчанию) обеспечивает возможность вертикального
	растяжения или сжатия изображения в соответствии с его
	содержимым.</dd>

      <dt><strong>-palette</strong> <em>спец-палитры</em></dt>

      <dd>Задает разрешение цветов выделенного изображению и
	число используемых цветов из палитр окон размещения
	изображения. Строка параметра спец-палитры может представлять
	собой либо одно десятичное число, задающее число используемых
	оттенков серого цвета, либо три десятичных числа, разделенных
	наклонными косыми чертами (/), задающих число используемых
	оттенков красного, зеленого и голубого цветов. Если строка
	состоит из одного десятичного числа, то будет выводиться
	монохромное изображение (оттенками серого цвета).</dd>

      <dt><strong>-width</strong> <em>число</em></dt>

      <dd>Задает ширину изображения в пикселах. Этот параметр
	оказывается полезным, в первую очередь, в ситуациях, когда
	пользователь строит изображение по частям. Значение ноль
	(принятое по умолчанию) обеспечивает возможность
	горизонтального растяжения или сжатия изображения в
	соответствии с его содержимым.</dd>
    </dl>
    
    <h2><a name=КОМАНДА_IMAGE></a>КОМАНДА IMAGE</h2>

    <p>При создании изображения типа <strong>photo</strong>
      Tk создает также новую команду, имя которой совпадает с именем
      вновь созданного изображения. С помощью этой команды можно
      выполнять различные операции над изображением. Она имеет
      следующий общий вид:</p>


    <pre>
      imageName параметр ?арг арг ...?
    </pre>

    <p><em>Параметр</em> и <em>арг</em>ументы уточняют поведение
      команды.</p>

    <p>Параметры, приводящие к дописыванию данных в изображение,
      обычно приводят к увеличению размеров изображения, за
      исключением случаев, когда пользователь задал ненулевые значения
      параметров конфигурации <strong>-width</strong> и/или
      <strong>-height</strong>; в последнем случае ширина и/или высота
      изображения не изменяются.</p>

    <p>Изображения типа photo поддерживают следующие команды:</p>

    <dl>
      <dt><em>имяИзображения</em> <strong>blank</strong></dt>

      <dd>Очищает изображение, т.е. устанавливает, что в изображении
	нет данных, поэтому при выводе оно оказывается прозрачным, и
	на его месте видно содержимое содержащего его окна.</dd>

      <dt><em>имяИзображения</em> <strong>cget</strong>
	<em>параметр</em></dt>

      <dd>Возвращает текущее значение параметра конфигурации с именем
	<em>параметр</em>. <em>Параметр</em> может быть любым из
	параметров команды <strong>image create photo</strong>.</dd>

      <dt><em>имяИзображения</em> <strong>configure</strong>
	?<em>параметр</em>? ?<em>значение параметр значение
	...</em>?</dt>

      <dd>Запрашивает значения параметров конфигурации изображения или
	изменяет их. Если <em>параметр</em> не указан, то возвращает
	список, содержащий значения всех допустимых в
	<em>имениПути</em> параметров (формат списка описан в
	<strong>Tk_ConfigureInfo</strong>). Если параметр задан, а его
	новое значение - нет, то команда возвращает часть полного
	списка, относящуюся к указанному параметру. Если заданы одна
	или несколько пар параметр-значение, то указанным параметрам
	примитива присваиваются новые значения, а команда возвращает
	пустую строку. Параметр может быть любым из параметров команды
	<strong>image create photo</strong>.</dd>

      <dt><em>имяИзображения</em> <strong>copy</strong>
	<em>исхИзобр</em> ?<em>параметр значение(я) ...</em>?</dt>

      <dd><p>Копирует область изображения с именем <em>исхИзобр</em>
	(которое должно быть изображением типа <em>photo</em>) в
	изображение с именем <em>имяИзображения</em>, возможно с
	растяжением пикселей и/или subsampling. Если параметры не
	заданы, то команда копирует в <em>имяИзображения</em> все
	исходное изображение, начиная с точки с координатами (0,0) в
	изображении <em>имяИзображения</em>. В команде могут быть
	заданы следующие параметры:</p>

	<dl>
	  <dt> <strong>-from</strong> <em>x1 y1 x2 y2</em></dt>

	  <dd>Задает предназначенную для копирования прямоугольную
	    область в исходном изображении. Точки с координатами
	    (<em>x1</em>,<em>y1</em>) и (<em>x2</em>,<em>y2</em>)
	    задают противоположные углы прямоугольника. Если параметры
	    <em>x2</em> и<em>y2</em> не заданы, то их значениями по
	    умолчанию являются координаты нижнего правого угла
	    исходного изображения. В копируемую область включаются
	    левая и верхняя стороны прямоугольника, но не его нижняя и
	    правая стороны. Значением параметра <strong>-from</strong>
	    по умолчанию является все исходное изображение.</dd>

	  <dt><strong>-to</strong> <em>x1 y1 x2 y2</em></dt>

	  <dd>Задает прямоугольную подобласть в изображении
	    <em>имяИзображения</em>. Точки с координатами
	    (<em>x1</em>,<em>y1</em>) и (<em>x2</em>,<em>y2</em>)
	    задают противоположные углы прямоугольника. Если
	    координаты <em>x2</em> и <em>y2</em> не заданы, то их
	    значениями по умолчанию являются значения координат
	    (<em>x1</em>,<em>y1</em>), к которым прибавлены размеры
	    исходной области (после subsampling???  и увеличения, если
	    они требуются). Если координаты <em>x2</em> и <em>y2</em>
	    заданы, то копируемая область будет при необходимости
	    воспроизведена несколько раз для замещения всего
	    отведенного прямоугольника.</dd>

	  <dt><strong>-shrink</strong></dt>

	  <dd>Указывает на то, что размер отведенной области должен
	    быть при необходимости уменьшен таким образом, чтобы
	    копируемый прямоугольник оказался в ее правом нижнем
	    углу. Если пользователь задал ненулевые значения
	    параметров конфигурации <strong>-width</strong> или
	    <strong>-height</strong> , то параметр
	    <strong>-shrink</strong> не окажет влияния на ширину или
	    высоту соответственно.</dd>

	  <dt><strong>-zoom</strong> <em>x y</em></dt>

	  <dd>Задает необходимость растяжения копируемой области с
	    коэффициентом <em>x</em> в X-направлении и с коэффициентом
	    <em>y</em> в Y-направлении. При задании этого параметра
	    каждый пиксел исходного изображения при копировании будет
	    представлен в виде прямоугольника x * y пикселей одного
	    цвета. Оба числа x и y должны быть положительными.</dd>

	  <dt><strong>-subsample</strong> <em>x y</em></dt>

	  <dd>Указывает на необходимость уменьшения исходного
	    изображения за счет использования только каждого x-го
	    пикселя в X-направлении и каждого y-го пикселя в
	    Y-направлении. Отрицательные значения параметров приводят
	    к отражению в соответствующем направлении. Если параметр
	    <em>y</em> не задан, то его значение по умолчанию
	    совпадает со значением параметра <em>x</em>.</dd>
	</dl>
      </dd>

      <dt><em>имяИзображения</em> <strong>get</strong> <em>x y</em></dt>

      <dd>Возвращает цвет пиксела с координатами (<em>x,y</em>) в
	указанном изображении в виде списка из трех целых чисел в
	промежутке от 0 до 255, описывающих соответственно его
	красную, зеленую и голубую составляющие.</dd>

      <dt><em>имяИзображения</em> <strong>put</strong> <em>данные</em>
	?<strong>-to</strong> <em>x1 y1 x2 y2</em>?</dt>

      <dd>Устанавливает цвета пикселей, заданные параметром
	<em>данные</em>. Этот параметр используется для формирования
	двумерного массива пикселей, который затем копируется в
	изображение <em>имяИзображения</em>. Данные представляют собой
	список строк, идущих сверху вниз, каждая из которых является
	списком цветов, идущих слева направо. Каждый цвет задается
	именем (например, <strong>blue</strong>) или в
	шестнадцатеричном виде (например, <strong>#2376af</strong>). С
	помощью параметра <strong>-to</strong> можно отвести область
	для размещения массива. Если заданы только координаты
	<em>x1</em> и <em>y1</em>, то верхним левым углом отведенной
	области является точка с координатами
	(<em>x1</em>,<em>y1</em>), а размеры области совпадают с
	размерами массива. Если указаны все четыре координаты, то они
	задают противоположные углы отведенного прямоугольника, и
	содержимое массива будет при необходимости повторено в X- и
	Y-направлениях для замещения всего отведенного
	прямоугольника.</dd>

      <dt><em>имяИзображения</em> <strong>read</strong> <em>имяфайла</em>
	?<em>параметр значение(я) ...</em>?</dt>

      <dd><p>Читает данные из файла с именем <em>имяфайла</em> в
	изображение с именем <em>имяИзображения</em>. Выполнение
	команды начинается с просмотра списка программ обработки
	форматов файлов изображений в поисках программы, способной
	интерпретировать данные в указанном файле; затем эти данные
	читаются из файла в изображение с именем
	<em>имяИзображения</em>. Команда может иметь следующие
	параметры:</p>

	<dl>
	  <dt><strong>-format</strong> <em>имя-формата</em></dt>

	  <dd>Задает формат данных в файле с именем <em>имяфайла</em>.
	    Точнее говоря, при поиске в списке программ обработки
	    будут просматриваться только те программы, имена которых
	    начинаются с <em>имени-формата</em>.</dd>

	  <dt><strong>-from</strong> <em>x1 y1 x2 y2</em></dt>

	  <dd>Задает прямоугольную подобласть в изображении,
	    описываемом данными файла, которую необходимо скопировать
	    в изображение с именем <em>имяИзображения</em>. Если
	    заданы только параметры <em>x1</em> и <em>y1</em>, то они
	    задают координаты левого верхнего угла подобласти, а ее
	    правый нижний угол совпадает с правым нижним углом всего
	    изображения в файле. Если заданы все четыре координаты, то
	    они задают два противоположных угла подобласти. Если этот
	    параметр не задан, то по умолчанию копируется все
	    изображение.</dd>

	  <dt><strong>-shrink</strong></dt>

	  <dd>Если присутствует этот параметр, то размер изображения с
	    именем <em>имяИзображения</em> при необходимости
	    уменьшается таким образом, чтобы прямоугольник, отведенный
	    под содержимое файла изображения, находился в правом
	    нижнем углу изображения с именем
	    <em>имяИзображения</em>. Если пользователь задал ненулевые
	    значения параметров конфигурации <strong>-width</strong>
	    или <strong>-height</strong>, то параметр
	    <strong>-shrink</strong> не будет оказывать влияния
	    соответственно на ширину или высоту изображения.</dd>

	  <dt><strong>-to</strong> <em>x y</em></dt>

	  <dd>Задает координаты верхнего левого угла прямоугольника в
	    изображении с именем <em>имяИзображения</em>, отводимого
	    под данные из файла. По умолчанию параметр имеет значение
	    (0,0).</dd>
	</dl>
      </dd>

      <dt><em>имяИзображения</em> <strong>redither</strong></dt>

      <dd>При выводе изображений типа photo используется алгоритм
	приближения (dithering) , который распространяет дискретные
	ошибки с пиксела на его соседей. Если данные для изображения
	<em>имяИзображения</em> поставляются частями, то результат
	приближения может быть не вполне корректным. Обычно эта
	некорректность на взгляд незаметна, однако при серьезных
	нарушениях с помощью данной команды можно пересчитать
	необходимые приближения в каждом окне, в котором выводится
	данное изображение.</dd>

      <dt><em>имяИзображения</em> <strong>write</strong> <em>имяфайла</em>
	?<em>параметр значение(я) ...</em>?</dt>

      <dd><p>Записывает изображение <em>имяИзображения</em> в файл с
	именем <em>имяфайла</em>. Может иметь следующие параметры:</p>

	<dl>
	  <dt><strong>-format</strong> <em>имя-формата</em></dt>

	<dd>Задает имя программы обработки файла изображения, которую
	    следует использовать при записи данных в файл. Точнее
	    говоря, данная подкоманда ищет первую программу обработки
	    в списке, начало имени которой совпадает с началом
	    имени-формата и которая способна записывать данные в
	    файл. Если этот параметр не задан, то эта подкоманда
	    использует первую программу обработки, способную
	    записывать данные в файл изображения.</dd>

	  <dt><strong>-from</strong> <em>x1 y1 x2 y2</em></dt>

	  <dd>Задает прямоугольную область в изображении с именем
	    <em>имяИзображения</em>, которую следует переписать в файл
	    изображения. Если заданы только значения <em>x1</em> и
	    <em>y1</em>, то они задают верхний левый угол
	    прямоугольника, а его нижний правый угол совпадает с
	    нижним правым углом изображения. Если заданы все четыре
	    координаты, то они задают противоположные углы
	    прямоугольника. Если параметр не задан, то по умолчанию
	    копируется все изображение.</dd>
	</dl>
      </dd>
    </dl>

    <h2><a name=ФОРМАТЫ_ИЗОБРАЖЕНИЙ></a>ФОРМАТЫ ИЗОБРАЖЕНИЙ</h2>

    <p>При создании программ обработки изображений типа photo
      предусмотрена возможность легкого добавления новых форматов
      файлов изображений. Все программы занесены в список. Добавление
      программы в список происходит в результате выполнения команды
      <strong>Tk_CreatePhotoImageFormat</strong>. В стандартном
      дистрибутиве Tk содержатся программы обработки для форматов
      PPM/PGM и GIF, которые автоматически заносятся в список при
      инициализации.</p>

    <p>При чтении файла изображения или обработке строки данных,
      заданной в параметре конфигурации <strong>-data</strong>,
      команда <strong>photo image</strong> просматривает программы
      обработки одну за другой, пока не найдется такая, которая
      утверждает, что она способна читать данные из файла или
      строки. Результатом поиска обычно бывает правильная программа
      обработки. В противном случае пользователь может задать имя
      программы обработки с помощью параметра
      <strong>-format</strong>.</p>

    <p>На самом деле команда <strong>photo image</strong>
      просматривает только те программы обработки, имена которых
      начинаются со строки, заданной параметром
      <strong>-format</strong> (при сравнении регистр не
      учитывается). Если, например, пользователь указал
      <strong>-format gif</strong>, то могут выполняться программы
      обработки GIF87 или GIF89, но не программа JPEG (если такие
      программы были внесены в список).</p>

    <p>При записи изображения в файл параметр <strong>-format</strong>
      обрабатывается несколько другим способом: строка, являющаяся его
      значением, должна начинаться с полного имени запрашиваемой
      программы обработки, за которым может следовать дополнительная
      информация. Эта дополнительная информация может, например,
      сообщать программе, какую из версий формата следует
      использовать.</p>

    <h2><a name=РАСПРЕДЕЛЕНИЕ_ЦВЕТОВ></a>РАСПРЕДЕЛЕНИЕ ЦВЕТОВ</h2>

    <p>При выводе изображения типа photo в окно команда
      <strong>photo image</strong> отводит цвета и,
      при необходимости, возмущает изображение, заменяя отсутствующие
      цвета доступными. Выделяемые цвета образуют куб: число возможных
      составных цветов представляет собой произведение чисел оттенков
      красного, зеленого и голубого цветов.</p>

    <p>Обычно выбор числа цветов определяется глубиной окна. Например,
      в 8-битовом окне PseudoColor команда <strong>photo
      image</strong> пытается отвести семь оттенков красного, семь
      оттенков зеленого и четыре оттенка голубого, всего 198 составных
      цветов. Для 1-битового окна StaticGray (монохромного) команда
      отводит два цвета, белый и черный. Для 24-битовых окон
      DirectColor или TrueColor команда отводит по 256 оттенков
      каждого из трех цветов. Если не удается отвести все цвета, то
      команда <strong>photo image</strong> уменьшает число оттенков
      каждого простого цвета и производит новую попытку
      размещения.</p>

    <p>Пользователь может частично управлять выбором числа цветов с
      помощью параметра конфигурации <strong>-palette</strong>. При
      использовании этого параметра в нем задается максимальное число
      используемых оттенков каждого из простых цветов. Кроме того с
      помощью этого параметра можно потребовать представления
      изображения оттенками серого цвета даже в цветном окне, задав
      одно число вместо трех, разделенных наклонными чертами.</p>
  </body>
</html>