# surf

Esboço de superfície 3d

## Seqüência de Chamamento

    surf(Z,<GlobalProperty>)
                surf(Z,color,<GlobalProperty>)
                surf(X,Y,Z,<color>,<GlobalProperty>)
                surf(<axes_handle>,...)

## Parâmetros

Z

  uma matriz real definindo as alturas da superfície. Não pode ser omitida. O dado Z é uma matriz`m` x`n`.

X,Y

  dois vetores ou matrizes reais: sempre ajustados juntos, estes dados definem um novo grid padrão. Estes novos componentes `X` e `Y` do grid devem coincidir com as dimensões de `Z` (ver a descrição abaixo).

color

  um matriz de reais opcional definindo valores de cores para cada ponto `(X(j),Y(i))` do grid (ver descrição abaixo).

<GlobalProperty>

  esta propriedade rerpresenta uma seqüência de pares de sentenças `{PropertyName,PropertyValue}` que definem propriedades globais de objetos aplicadas a todas as curvas criadas neste esboço. Para uma completa visualização das propriedades disponíveis veja GlobalProperty.

<axes_handle>

  este argumento opcional força os eixos a aparecerem dentro dos eixos selecionados dados por `axes_handle` ao invés dos eixos correntes (ver gca).

## Descrição

`surf` desenha uma superfície parametrizada colorida utilizando um grid retangular definido pelas coordenadas `X` e `Y` (se `{X,Y}` não forem especificados, este grid é determinado utilizando-se as dimensões da matriz `Z`) ; em cada ponto deste grid, uma coordenada Z é dada utilizando-se uma matriz `Z` (apenas dados obrigatórios). `surf` foi criada para lidar melhor com a sintaxe do Matlab. Para melhorar a compatibilidade gráfica, usuários do Matlab devem utilizar `surf` (ao invés de plot3d).

Especificação de entrada de dados:

Neste parágrafo, e para sermos mais claros, não mencionaremos os argumentos opcionais de `GlobalProperty` ojá que eles não interferem na entrada de dados (exceto pelas propriedades `"Xdata"`, `"Ydata"` e `"Zdata"`, ver GlobalProperty). É assumido que todos estes argumentos opcionais podem estar presentes também.

Se `Z` é a única matriz especificada, surf(Z) esboça a matriz `Z` versus o grid definido por `1:size(Z,2)` ao longo do eixo x e `1:size(Z,1)` ao longo do eixo.

Se uma tripla `{X,Y,Z}` for fornecida, `Z` deve ser uma matriz de size(`Z`)= [`m`x`n`], `X` or `Y` can be :

- a) um vetor: se `X` for um vetor, length(`X`)=`n`. Respectivamente, se `Y` for um vetor, length(`Y`)=`m`.

  b) uma matriz: neste caso, size(`X`) (ou size(`Y`)) deve ser igual a size(`Z`).

Especificação de entrada de cores:

Como citado acima, a superfície é criada sobre um gride retangular de apoio. Consideremos duas variáveis independentes `i` e `j` tais que:

Este grid retangular imaginário é utilizado para se contruir o suporte da superfície real sobre o plano `XY` . De fato, os dados `X`,`Y` e `Z` possuem o mesmo tamanho (mesmo se `X` ou `Y` for um vetor, ver abaixo) e podem ser considerados como três funções `x(i,j)`, `y(i,j)` e `z(i,j)` especificando a superficie desejada. Se `X` ou `Y` forem vetores, eles são internamente tratados para produzir boas matrizes de dimensões correspondentes às dimensões da matriz `Z` (e o grid é forçosamente uma região retangular).

Considerando as três funções `x(i,j)`, `y(i,j)` e `z(i,j)`, a porção da superfície definida entre dois `i` e `j` consecutivos é chamada remendo.

Por padrão, quando nenhuma matriz de cores é adicionada a uma chamada a surf, o parâmetro de cor é ligado o dado `Z` . Quando uma matriz de cores `color` é dada, pode ser aplicada aos remendos de duas formas diferentes: nos vértices, ou no centro de cada remendo.

É por isto que, se `Z` é uma matriz [`m`x`n`] , a dimensão da matriz `color C` pode ser [`m`x`n`] (uma cor definida por vértice) ou [`m-1`x`n-1`] (uma cor definida por remendo).

A representação de cores também varia quando se especifica algumas GlobalProperties (propriedades globais):

A propriedade `FaceColor` ajusta o padrão de gradação: pode ser `'interp'` ou `'flat'` (modo padrão). Quando `'interp'` é selecionado, é realizado uma interpolação bilinear de cores no remendo. Se size(`C`) é igual a size(`Z`)-1 (i.e. for fornecida apenas uma cor ao remendo) então a cor dos vértices definindo o remendo é ajustada para a dada cor do remendo.

Quando `'flat'` (modo padrão) é habilitado, é utilizada uma representação de cores de facetadas (uma cor por remendo). Se size(`C`) é igual a size(`Z`) (i.e. foi fornecida apenas uma cor por os vértices), as últimas linha e coluna de `C` são ignoradas.

Os argumentos `GlobalProperty` devem ser usados para customizar a superfície. Aqui está uma breve descrição de como funcionam:

GlobalProperty

  esta opção pode ser utilizada para especificar como todas as superfícies serão desenhadas. Deve sempre ser um par de sentenças constituidos de um string definindo `PropertyName`, (nome da propriedade) e seu valor associado `PropertyValue` (que pode ser um inteiro ou outra coisa... dependendo do tipo de `PropertyName`). Note que você pode ajustar múltiplas propriedades : a cor da face e da borda, dados de cores, mapeamento de dados de cores, cor do marcador (plano de fundo e primeiro plano), visibilidade, recorte, espessura das bordas da superfície... (ver GlobalProperty )

  Note que todas essas propriedades podem ser (re-)ajustadas através das propriedades da entidade superfície (ver surface_properties).

## Observações

Por padrão, esboços sucessivos de superfície são superpostos. Para limpar o esboço anteirior, use `clf()`. Para habilitar o modo `auto_clear` (limpeza automática) como modo padrão, edite seus eixos padrões fazendo:

da=gda();

da.auto_clear = 'on'

Entre com o comando `surf` para visualizar uma demonstração.

## Exemplos

    // inicialização de Z

    Z= [   0.0001    0.0013    0.0053   -0.0299   -0.1809   -0.2465   -0.1100   -0.0168   -0.0008   -0.0000
        0.0005    0.0089    0.0259   -0.3673   -1.8670   -2.4736   -1.0866   -0.1602   -0.0067    0.0000
        0.0004    0.0214    0.1739   -0.3147   -4.0919   -6.4101   -2.7589   -0.2779    0.0131    0.0020
       -0.0088   -0.0871    0.0364    1.8559    1.4995   -2.2171   -0.2729    0.8368    0.2016    0.0130
       -0.0308   -0.4313   -1.7334   -0.1148    3.0731    0.4444    2.6145    2.4410    0.4877    0.0301
       -0.0336   -0.4990   -2.3552   -2.1722    0.8856   -0.0531    2.6416    2.4064    0.4771    0.0294
       -0.0137   -0.1967   -0.8083    0.2289    3.3983    3.1955    2.4338    1.2129    0.2108    0.0125
       -0.0014   -0.0017    0.3189    2.7414    7.1622    7.1361    3.1242    0.6633    0.0674    0.0030
        0.0002    0.0104    0.1733    1.0852    2.6741    2.6725    1.1119    0.1973    0.0152    0.0005
        0.0000    0.0012    0.0183    0.1099    0.2684    0.2683    0.1107    0.0190    0.0014    0.0000];

    //superfície simples
    surf(Z); // note que X e Y são determinados pelas dimensões de Z

    //a mesma superfície com faces vermelhas e bordas azuis
    scf(2); // nova figura de número 2
    surf(Z,'facecol','red','edgecol','blu")

    // inicialização de X e Y
    // NB: aqui, X tem as mesmas linhas e Y tem as mesmas colunas
    X = [ -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
       -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
       -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
       -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
       -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
       -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
       -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
       -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
       -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
       -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000];

    Y= [   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000
       -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333
       -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667
       -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000
       -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333
        0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333
        1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000
        1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667
        2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333
        3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000];

    // exemplo 1
    scf(3)
    surf(X,Y,Z)

    //exemplo 2
    // como você pode ver, o grid não é necessariamente retangular
    scf(4)
    X(1,4) = -1.5;
    Y(1,4) = -3.5;
    Z(1,4) = -2;
    surf(X,Y,Z)

    // exemplo 3
    // X e Y são vetores => mesmo comportamento que a amostra 1
    // com vetores, o grid é inevitavelmente retangular
    scf(5)// nova figura de número 5
    X=[ -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000];
    Y=X;
    surf(X,Y,Z)

    //exemplos com LineSpec e GlobalProperty:
    xdel(winsid()) // destruindo todas as figuras existentes
    surf(Z,Z+5) // array de cores especificado
    e=gce();
    e.cdata_mapping='direct' // o padrão é 'scaled' relativo ao mapa de cores colormap
    e.color_flag=3; // modo de gradação interpolada. O padrão é 4 (modo 'flat') para surf

    scf(2)
    surf(X,Y,Z,'colorda',ones(10,10),'edgeco','cya','marker','penta','markersiz',20,'markeredg','yel','ydata',56:65)

    scf(3)
    surf(Z,'cdatamapping','direct')
    scf(4)
    surf(Z,'facecol','interp') // interpolated shading mode (color_flag == 3)

    scf(10)
    axfig10=gca();
    scf(11);
    surf(axfig10,Z,'ydat',[100:109],'marker','d','markerfac','green','markeredg','yel') // draw onto the axe of figure 10

    xdel(winsid())

## Ver Também

- plot2d
- clf
- xdel
- delete
- LineSpec
- GlobalProperty