Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- Ignition Robotics (link em inglês)
- Redator técnico:
- Um le tailandês
- Nome do projeto:
- Tutoriais de Ignition Physics e documentação da API
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Motivação
A biblioteca Ignition Physics permite o uso flexível dos mecanismos físicos transferidos para o back-end da simulação do Ignition Gazebo. Vários mecanismos físicos externos podem ser adaptados à biblioteca como plug-ins compostos por diferentes conjuntos de recursos, de acordo com as capacidades e os contextos do aplicativo, para possibilitar a simulação do gazebo. No entanto, o estágio atual da biblioteca não oferece:
- tutoriais abrangentes sobre como criar plug-ins de física personalizados que usam mecanismos de física personalizados para alimentar a simulação.
- documentação da API coerente;
Esta proposta visa resolver esses problemas para uma melhor manutenção do projeto e orientar novos colaboradores e usuários de uma forma mais geral. Os detalhes do processo de documentação serão discutidos na próxima seção e seguidos pela seção de marcos para planejar o prazo para a conclusão do projeto. Por fim, citamos algumas observações sobre a documentação atual.
Descrição
Este projeto tem duas metas principais:
- Criar tutoriais detalhados sobre como criar um plug-in de física personalizado fazendo interface com a API da biblioteca atual.
- Melhoria da documentação atual da API da biblioteca para fins de manutenção e colaboração.
Atualmente, o DART é o único mecanismo de física de suporte dessa biblioteca. Portanto, os tutoriais serão relacionados ao DART. Estes tutoriais iniciais serão considerados:
- Introdução: descreve a arquitetura de alto nível da biblioteca Ignition Physics, os mecanismos de física com suporte e os objetivos dela.
- Instalação: orienta o usuário a instalar os mecanismos físicos necessários, dependendo dos contextos do aplicativo. Este tutorial também mostra exemplos de configurações para cada plug-in de mecanismo de física de adaptação de uma simulação específica.
- Uso do plug-in do DART: descreve um exemplo de uso do mecanismo de física do DART na simulação do Gazebo. O tutorial consiste em uma sequência de execuções e configurações para iniciar essa biblioteca como o back-end da simulação do Gazebo em um ambiente de exemplo específico.
- Criar plug-in personalizado: orienta novos usuários ou desenvolvedores a criar um plug-in personalizado com base em um mecanismo de física personalizado usando algumas formas de arquivos de configuração (possivelmente modelos de classe) e desenvolve uma interface entre a API physics Engine e essa API Library. Algumas verificações de integridade podem ser observadas no final do tutorial.
- Usar vários plug-ins em uma simulação (precisa ser discutido): descreve como usar vários plug-ins simultaneamente durante a execução para uma simulação de exemplo.
Outros planejamentos das estruturas, descrições e conteúdos dos tutoriais serão discutidos nesse período de envolvimento da comunidade. É de fato que o autor desses tutoriais precisa garantir a validade das etapas do tutorial antes de mesclá-lo ao repositório.
Para a documentação da API, é possível adaptar o estilo de documentação do Google C++ para essa biblioteca. Por exemplo, todas as classes precisam ter uma descrição no nível da classe. Além disso, todas as funções públicas devem ser documentadas com uma descrição, todos os seus argumentos, bem como possíveis valores de retorno e exceções. É vantajoso que as classes mais importantes (por exemplo, dartsim::RetrieveWorld, Feature etc.) sejam documentadas primeiro como uma abordagem de cima para baixo mais fácil. Outros estilos de documentação e identificação de classe importantes serão discutidos no período de vínculo com a comunidade.
Milestones
Esta seção planeja um prazo inicial para concluir as metas mencionadas do projeto. O planejamento de tempo é o seguinte:
17 de ago. a 13 de set.: laço comunitário:
- Marcar reuniões para estabelecer escopos do projeto e planejamentos de tutoriais, bem como expectativas do redator e dos mentores.
- Tenha uma visão geral do código-fonte do Ignition Physics.
14 de setembro a 31 de outubro: elabore os tutoriais mencionados com refinamentos iterativos entre os mentores e o redator em reuniões.
1o a 30 de novembro: escreva a documentação da API para as classes mais importantes e compile a documentação usando o Doxygen.
1o a 5 de dezembro: elabore o relatório do projeto.
Depois do GSoD 2020: gostaria de continuar conectado com a Ignition Robotics para melhorar ainda mais e manter meu trabalho.
Observações finais
É essencial revisar o README.md atual na página inicial do Ignition Physics (em inglês), porque a instalação binária que usa o apt-get não funciona no Ubuntu 18.04. A seção de instalação de origem também precisa de revisão devido à formatação incorreta.